APIバージョニング

APIバージョニングとは

API バージョニングは、既存の利用者を壊さずに API を変更していくためのバージョン管理の仕組みです。公開した [[REST API]] は自分だけのものではありません — 変更した瞬間、その API を呼んでいる誰かのアプリが動かなくなるかもしれないのです。

鍵になるのが破壊的変更(breaking change)かどうかの見極めです。

変更内容破壊的?
レスポンスにフィールドを追加する通常は非破壊
フィールドを削除・改名する破壊的
フィールドの型や意味を変える破壊的
必須パラメータを追加する破壊的

非破壊な変更はそのまま出せますが、破壊的変更には新しいバージョンが必要です。

バージョンの付け方

代表的な方式は3つあります。

1. URLパス      : GET /v1/users → GET /v2/users
2. リクエストヘッダー : GET /users
                   X-API-Version: 2026-07-01
3. クエリパラメータ  : GET /users?version=2
  • URLパス方式が最も広く使われます。どのバージョンを呼んでいるか一目瞭然で、ブラウザでも試しやすいのが利点です
  • ヘッダー方式は URL を汚さない反面、呼び出しの見た目からバージョンが分かりません。Stripe のように日付をバージョンにする例もあります

なお、バージョン番号の意味付けには [[セマンティックバージョニング]] の「メジャーバージョンを上げる=破壊的変更あり」という考え方が下敷きになっています。

古いバージョンの畳み方

バージョンを増やすことよりも、減らすことの方が難しい問題です。全バージョンを永遠に維持するとコストが膨らみ続けるため、計画的に廃止します。

  1. 非推奨化(deprecation)を告知する — ドキュメントとレスポンスヘッダーで「このバージョンは廃止予定」と伝える
  2. 移行期間を十分に設ける — 利用者が新バージョンへ移る時間を確保する
  3. 廃止(sunset)する — 期限後に旧バージョンを停止する

初学者向けポイント

  • まず「フィールドの追加は安全、削除・改名は危険」という感覚を持ちましょう。安易な改名が最も多い事故原因です
  • 破壊的変更を避ける設計の工夫として、[[GraphQL]] はクライアントが必要なフィールドだけを指定する方式でこの問題を緩和しています
  • 自社内だけで使う API でも、フロントエンドとバックエンドのデプロイタイミングがずれる以上、互換性の考え方は同じように必要です

関連技術とのつながり

  • [[REST API]] — バージョニングの主戦場。URL 設計の一部
  • [[セマンティックバージョニング]] — 破壊的変更とメジャーバージョンの関係
  • [[HTTP]] — ヘッダー方式やステータスコードでの非推奨告知に関わる
  • [[GraphQL]] — バージョンを増やさずに進化させる別のアプローチ
Q: 破壊的変更に該当するのはどれ?
- [ ] レスポンスに新しいフィールドを追加する
- [x] 既存フィールドを削除・改名する
- [ ] ドキュメントの誤字を修正する
解説: 削除・改名・型変更・必須パラメータ追加は利用者のコードを壊す破壊的変更です。追加は通常非破壊です。

Q: 最も広く使われているバージョン指定方式はどれ?
- [x] URLパスに /v1 のように含める方式
- [ ] リクエストボディにバージョンを書く方式
- [ ] ユーザーエージェントから自動推測する方式
解説: URL パス方式はどのバージョンを呼んでいるか一目で分かり、最も広く使われています。

Q: 古いバージョンを廃止する際の正しい手順はどれ?
- [ ] 予告なく即座に停止して新バージョンへの移行を強制する
- [x] 非推奨化を告知し、移行期間を設けてから廃止する
- [ ] 廃止せず全バージョンを永遠に維持し続ける
解説: 告知→移行期間→廃止の順で計画的に畳みます。全バージョンの永久維持はコストが膨らみ続けます。