API バージョン管理
公開 API は Shopify と同じ方式である 日付版バージョン を採用しており、開発対象のバージョンが知らないうちに変わることはありません。日付版バージョンは互換性のない変更の大まかな境界です。同一バージョン内でも、スキーマは追加のみの形で進化し続けます。
バージョン名
バージョン名は YYYY-MM の形式で、月は四半期の開始月です：2026-01、2026-04、2026-07、2026-10。新しい日付版バージョンは 互換性のない変更があるときにのみ 切られます。互換性のない変更がない四半期は飛ばされるため、バージョンは比較的まれにしか登場しません。
最新の開発状況を追う unstable バージョンもあり、安定版リリース前に変更を先取りして確認できます。本番の連携をこれに対して構築しないでください。
バージョンの選択
優先順位の高い順に 2 つの方法があります。
- URL パス（推奨）： エンドポイントにバージョンを含めます —
…/backend/<subdomain>/api/2026-07/graphql。明示的で、キャッシュしやすく、そのままコピーできます。 - リクエストヘッダー： 素の
…/backend/<subdomain>/graphqlエンドポイントに対してX-Api-Version: 2026-07を送信します。
バージョンを省略した場合 — あるいは未知のバージョンやサポート終了済みのバージョンを指定した場合 — リクエストは最新版ではなく、まだサポートされている最も古いバージョン で処理されます。互換性のない変更に黙って移されることはありません。継続して運用するつもりの連携では、必ずバージョンを明示的に固定してください。
すべてのレスポンスは、それを処理したバージョンを X-Api-Version ヘッダーで返します。どの契約が応答したかを常に把握でき、既定の動作に頼っていた場合のずれも検知できます。
サポート期間
安定版バージョンは 12 か月以上 サポートされ、次のバージョンとは 9 か月以上重複 します。実際には常時 2〜3 のバージョンが有効で、移行のための余裕のある期間が確保されます。バージョンのサポート終了日は、そのバージョンの公開日に発表されます。
何が互換性のない変更にあたるか
同一バージョン内では 追加型 の変更を行うことがあり、クライアントはそれを許容する必要があります。
- 新しい型、クエリ、ミューテーションの追加
- 既存フィールドへの 省略可能な 引数の追加
- オブジェクト型へのフィールドの追加
- 列挙型への値の追加（列挙型が閉じていると決して仮定しないでください）
新しい日付版バージョン は、本当に互換性のない変更のためにのみ用意されます。フィールドや型の削除・改名、null 許容性の厳格化、引数や既定値の意味の変更などです。これらが既存バージョンの内部で起きることはありません。固定したバージョンは、そのサポート終了日まで動作を維持します。
非推奨
非推奨は 2 つの方法で通知されるため、何かが壊れる前に把握できます。
- スキーマ上。 廃止予定のフィールドには
@deprecatedが付き、代替を示す理由が添えられます。イントロスペクションと GraphQL Playground が、これをすべてのクライアントに自動的に提示します。 - レスポンス上。 リクエストが実際に非推奨フィールドを解決すると、レスポンスに
X-Api-Deprecated-Reasonヘッダー（および対応するextensions.deprecationsエントリ）が付き、そのリクエストが触れた具体的な非推奨項目が示されます。自分で探しにいかなくても、遭遇した時点でログに現れます。
非推奨フィールドは、公開された最短期間は維持されたうえで、後続の日付版バージョンで削除されます。