SquareではAPIが2つ存在します。v1とv2と呼ばれているのですが、双方に互換性はありません。開発者としてどちらのAPIを使っていくべきなのか、Square Connect API Documentationに書かれていますので簡単に紹介します。
v1を使って作られたアプリケーションはv2に載せ替えるべき?
いえ、それはありません。現状、v1で提供されている機能すべてをv2で提供していません。アプリケーションは必要に応じてv1とv2、両方を使うことができます。
v1とv2の共通機能はありますか?
パラメータフォーマットは同じです
GETまたはDELETEの場合はクエリストリングを使います。POST/PUTの場合はボディを使ってリクエストを送信します。
ヘッダーは共通です
すべてのリクエストは下記のリクエストヘッダーを持っています。
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json
OAuth APIエンドポイント
OAuth APIのエンドポイントは変更していません。
v1とv2で変更した場所はありますか?
日付フォーマット
v2はすべての日付フォーマットがRFC 3339になりました。v1はISO 8601です。
ページネーション
v2ではcursorパラメータがレスポンスに含まれます。これが次のデータにアクセスするためのURLになります。v1ではLinkというヘッダーがレスポンスに含まれています。
並び順
v2では日付毎(新しい順)に並んで返ってきます。また、sort_orderを使って並び順を変更できます。v1では古いもの順に並んで返ってきます。並び替える際のキーはorderです。
エラーフォーマット
v2ではレスポンスボディにerrorsがあり、そこにエラー情報が入ってきます。つまり複数のエラーがあった場合は配列で返ってきます。v1の場合は一つのエラーのみ返るようになっています。
v1とv2ではレスポンスの形式も異なりますので、必要な情報が取れるかを双方で確認して使うのが良いかと思います。個人的な印象としては v2 のが洗練されているように見えますが、v1のが結果の項目が多いように見えます。