※この記事で言及されている2020年4月の旧バージョンの廃止については7月まで延期されました。詳しくはこちらのブログをご参照ください。
2019年4月にShopifyがAPIのバージョン管理を導入するまで、Shopifyアプリが連携できるAPIは最新形式のものだけでした。マーチャント向けの機能がリリースされると、その機能に結びついたAPIも同様に進化することになり、アプリもまた正常に機能し続けるために新しいその方法をすばやく適用する必要がありました。
このようなデベロッパー体験は理想的なものとはいえません。アプリがいつ機能しなくなるか特定の日を知ることはむずかしく、変更のせいで開発ロードマップがひっくり返る可能性もありました。こうした点を解決するために、ShopifyはAPIのバージョン管理を導入し、明確で定期的なリリースと安定性を提供することになりました。
バージョンリリースの1年目のサイクルが終わろうとしている今、その仕組みをあらためて確認すると同時に、2020年に注意すべき点を見ていきたいと思います。
バージョン管理の仕組み
まずは、ShopifyのAPIバージョン管理の基本を振り返っておきましょう。
1.四半期ごとに新しいバージョンをリリースします
通常、リリースは1月1日、4月1日、7月1日、10月1日におこなわれます。バージョン名は年月の組み合わせ（例：2020–01）となるので、バージョンの安定時期を識別しやすく、複数のバージョンのタイムラインも比較しやすくなっています。
2.リクエストURLの指定により、アプリは特定のバージョンのAPIをリクエストします
ShopifyのAPIはつねに進化していますが、APIのコントラクトが一定に保たれるよう、アプリは安定したバージョンを選択して構築できます。これはつまり、指定したバージョン以降の機能にアクセスするにはリクエストURLをアップデートする必要があることを意味していますので、ご注意ください。
3.マーチャント向けの機能を継続的にリリースします
最新の安定したAPIに影響を与えることなく機能を追加するために、Shopifyはリリース候補というコンセプトを用いています。このリリース候補はシンプルにいえば次のAPIバージョンのことで、同じ年月形式のフォーマットを使用し、リクエストの対象となることができます。この中には、リリースされたばかりの最新の機能セットがあります。リリース候補は継続的に進化しているため、アプリが日常的に消費するAPIとしては使用しないでください。
安定性と新機能へのアクセスという2点のメリットを得るために、アプリの日常的なリクエストは安定バージョンに依拠し、リリースされたばかりの新機能を使うときだけリリース候補の特定のコールを使用することをお勧めします。
4.アプリが特定のバージョンをリクエストしない場合、サポートされている一番古いバージョンが提供されます
これにより、バージョンが更新されても既存のアプリは新しいURLにアップデートすることなく機能し続けることができます。このコンセプトは、サポートされなくなったバージョンを指定してコールするアプリに対しても適用されます。
たとえば、2019-04をサポートが終了してからもリクエストし続けると、サポートされているもっとも古いバージョン、つまり2019-07が提供されることになります。
5.各バージョンは1年間サポートされます
一定のバージョンのサポートを打ち切ることで、Shopifyはチームをアジャイルに保つことができ、長期的な観点からマーチャントとShopifyプラットフォームにとってベストなサービスのために、必要な変更を提供できます。各バージョンは1年間サポートされますが、実際にアプリが新しい変更を採用して従来の挙動が利用不可になるまでの間に新機能を活用できる期間は9ヶ月ということになります。
ShopifyにおけるAPIバージョン管理の基本をここまで見てきたので、次は2020年のために知っておくべき主要な情報を確認しておきましょう。
サポートされないバージョン
今回の投稿のタイミングは偶然ではありません。バージョン管理の導入から1年が経過しようとしているため、サポートされないAPIバージョンが初めて出てくることになります。
つまり、2020年の4月1日をもって、以下の変更がAPIに反映されます。
・2019-04バージョンのサポートは終了します。
・APIバージョンを指定しないリクエストには、2019-07バージョンのAPIが提供されます。
・2019-04バージョンのリクエストで2019-04を受け取ることはできず,2019-07バージョンのリクエストに転送されます。
・2019-04に設定されたwebhookの場合も同様です。
・2020-04バージョンが安定し、一般利用の準備が整います。
※もっとも重要な点は、これからデフォルトになる2019-07バージョンには重大なAPIの変更が含まれていることです。2019-07バージョンでリクエストの不具合がアプリに発生している場合、2020年4月1日までに必要なアクションを実行してそれらのリクエストを移行する必要があります。これを怠るとリクエストが失敗してアプリが機能しなくなります。
※マーチャントへの影響を最小限におさえるために、仮にアプリが4月1日以降にもまだサポート未対応のAPIを使用している場合、Shopifyはマーチャントに向けてそのアプリがすでにサポート外であることを通知します。また場合によっては、Shopifyアプリストアのリストから外すこともあります。
それでは2019-07に取り入れられた大きな変更点を個別に見ておきましょう。
重要な変更
以下の内容は4月に導入される重要な変更です。下記のものをアプリで使用している場合、アプリの不具合を避けるためにアップデートを実行してください。
1.ページネーション
ページベースのページネーションは削除され、カーソルベースのページネーションに置き換わっています。
Shopifyのエンジニアチームがこちらのエンジニアブログでこの変更の詳細と呼び出し方の移行について書いているので、その理由がわかります。
要点：pageパラメータの使用をやめ、代わりにpage_infoを使用してください。
2. collectから削除されたfeaturedフィールド
collectエンドポイントからfeaturedフィールドが削除されています。
この特定フィールドを使用していない場合でもRESTはデフォルトですべてを返します。そのためcollectエンドポイントを使用すると、この廃止についての通知を受け取ることになります。
要点：リクエストURLを2019-07またはそれ以降のAPIバージョンにアップデートしてください。
3. WebhookへのGraphQL Admin IDの追加
Webhookのペイロードにgraphql_admin_idを追加しました。レスポンスにおけるGraphQLのコールが容易になり、RESTペイロードとの一貫性が高まります。これにより古いバージョンのRailsアプリで問題が生じました。みなさんがRailsを使用していなくても、WebhookのAPIバージョンを定期的にアップデートすることをお勧めします。そうすれば現在のバージョンがサポートされなくなってもペイロードが変更されないようにできます。
要点：Webhook APIのバージョンを2019-07またはそれ以降のバージョンにアップデートしてください。
4.Delivery Profilesへの変更
activatedCarrierServicesは複数発送元と互換性がないため削除されました。代わりに配送業者と適応国を含むavailableCarrierServicesを使ってください。
要点：配送業者についての情報が必要な場合はavailableCarrierServicesを利用してください。
5.在庫管理
2018年の3月にバリアントの在庫を直接変更することは非推奨になりましたが、2019-10のバージョンで、古い在庫管理の振る舞いは全てのアプリから削除されます。これは、全てのアプリは商品のバリアントに対してinventory_quantityもinventory_quantity_adjustも使えないことを意味します。またアプリはlocation_idを指定せずにフルフィルメントを作成したり返金や在庫補填をすることができなくなります。
要点：複数ロケーションへの移行を行ってください。
最新の変更情報を得るには
今後の変更について知っておくのは良いことですが、アプリ全体において重要な変更を個々に特定するのは、多くの場合困難になり得ます。この絞り込みを容易にするため、ShopifyはみなさんのAPI使用状況に応じて自動的にデータを生成する以下のツールを導入しました。
1. APIヘルス
パートナーダッシュボードにはアプリごとにAPIヘルスレポートが備わっていて、影響のある変更について個別に表示します。その中には特定のエンドポイント、移行ガイドへのリンク、廃止リクエストが最後に検出されたときのタイムスタンプが含まれています。
2. Deprecation（廃止）ヘッダー
アプリ内でX-Shopify-API-Deprecated-Reasonヘッダーの存在をログに残すことで、今後の変更をモニタリングする必要もあります。このヘッダーは9ヶ月以内にサポートされなくなる廃止リクエストに付加されています。ヘッダーに返されるリンクに従ってリクエストのアップデートをおこなってください。
3. Eメール
すべてのアプリには関連する緊急用デベロッパーメールがあり、保留中の廃止案件について通知するために使われています。これらのメールでAPIヘルスレポートと同等の情報を得ることができます。プライベートアプリはパートナーアカウントに関連付けられていないため、このタイプのアプリにとって影響のある変更に関する通知を受け取るおもな方法がこのEメールとなります。
2020年4月のリリースに向けて
プラットフォームに変更を加えるとパートナーのみなさんに労力を強いることになることをShopifyは理解しています。バージョン管理によってこのプロセスが予測可能になり、混乱が少しでも減る助けになることを願っています。
この4月には2019-04バージョンが廃止となり、サポートされる一番古いバージョンは2019-07になります。アプリの準備をお忘れなく。
2019-07バージョンにおける変更の全容とその影響範囲については、こちらのリリースノートをご確認いただくか、パートナーダッシュボードをご確認ください。
原文：Alex Bradley 翻訳：深津望
Shopifyパートナープログラムでビジネスを成長させる
マーケティング、カスタマイズ、またはWebデザインや開発など提供するサービスに関係なく、Shopifyパートナープログラムはあなたを成功へと導きます。プログラムの参加は無料で、収益分配の機会が得られ、ビジネスを成長させる豊富なツールにアクセスできます。情熱的なコマースコミュニティに今すぐ参加しましょう！
