フレームワーク活用ガイドひとことで言うと#
APIに変更を加える際に、既存のクライアントを壊さずに新機能を提供するためのバージョン管理手法。URLパス、ヘッダー、クエリパラメータなど複数の方式があり、APIの性質と利用者に応じて適切な戦略を選ぶ。
押さえておきたい用語#
- 破壊的変更（Breaking Change）
- 既存クライアントのコードを修正しなければ動かなくなる変更。フィールド削除、型変更、必須パラメータ追加など。
- 後方互換性（Backward Compatibility）
- 新バージョンが古いクライアントからのリクエストも正しく処理できる性質。
- サンセット（Sunset）
- 古いAPIバージョンの廃止・終了を指す。Sunset HTTPヘッダーで廃止日を事前通知する。
- Deprecation（非推奨）
- まだ動作するが今後廃止予定であることを示す状態である。廃止前の猶予期間として設定する。
- セマンティックバージョニング
メジャー.マイナー.パッチ形式のバージョン番号。メジャーアップは破壊的変更を意味する規約。
APIバージョニングの全体像#
こんな悩みに効く#
- APIの仕様を変更したいが、既存クライアントへの影響が怖くて手を出せない
- バージョン管理のルールが曖昧で、破壊的変更が意図せずリリースされてしまう
- 古いバージョンのAPIがいつまでも残り、メンテナンスコストが膨らんでいる
基本の使い方#
主要なバージョニング方式の中から、APIの特性に合ったものを選ぶ。
- URLパスバージョニング:
/api/v1/users→/api/v2/users。最も直感的で広く採用されている - ヘッダーバージョニング:
Accept: application/vnd.myapi.v2+json。URLをクリーンに保てる - クエリパラメータ:
/api/users?version=2。実装は簡単だがキャッシュに課題 - コンテントネゴシエーション: Accept-Versionヘッダーで指定
ポイント: URLパスバージョニングが最もシンプルで、ドキュメントやデバッグも容易。迷ったらこれを選ぶ。
どの変更にバージョンアップが必要かのルールを定義する。
- 非破壊的変更（バージョンアップ不要）: フィールドの追加、オプショナルパラメータの追加、新エンドポイントの追加
- 破壊的変更（バージョンアップ必要）: フィールドの削除・リネーム、レスポンス構造の変更、必須パラメータの追加、エンドポイントの削除
ポイント: 加算的な変更は安全、削除・変更は危険という原則を全員が理解する。
古いバージョンをいつ、どのように廃止するかを事前に決めておく。
- 廃止予告期間: 新バージョンリリースから最低6〜12ヶ月
- 段階的廃止: Deprecatedヘッダーの付与 → 利用者への通知 → サンセット
- Sunset HTTPヘッダー:
Sunset: Sat, 01 Mar 2027 00:00:00 GMTで廃止日を通知
ポイント: 廃止ポリシーを最初から公開しておくことで、クライアントの移行を促しやすくなる。
クライアントがスムーズに新バージョンに移行できる環境を整える。
- マイグレーションガイドを提供する（変更点と対応方法）
- 両バージョンの並行稼働期間を設ける
- 旧バージョンの利用状況をモニタリングし、残存クライアントに個別連絡する
ポイント: 移行のハードルを下げることで、旧バージョンの保守期間を短縮できる。
具体例#
状況: 商品APIのレスポンスにpriceフィールド（数値）があったが、海外展開で多通貨対応が必要に。priceをpricesオブジェクト（通貨ごとの配列）に変更する破壊的変更。
対応:
/api/v2/productsを新設。prices: [{currency: "JPY", amount: 1000}, {currency: "USD", amount: 7.5}]形式/api/v1/productsはそのまま維持。priceフィールドを引き続き返す- v1のレスポンスに
Deprecation: trueヘッダーとSunset: 2027-03-01を付与 - API利用者48社にメールで変更通知とマイグレーションガイドを送付
8ヶ月で全48社がv2に移行完了。移行期間中の障害ゼロ。v1を安全に廃止し、保守コストを月40時間削減した。
状況: 3年間で5つのメジャーバージョンが並行稼働。廃止ポリシーがなく、v1にまだ月間12万リクエスト。エンジニア2名が旧バージョンの保守に専任。
施策:
- 廃止ポリシーを策定し公開（新バージョンから12ヶ月でサンセット）
- 各バージョンの利用状況ダッシュボードを構築
- v1〜v3の利用者にマイグレーションガイドと個別サポートを提供
- Sunsetヘッダーを段階的に付与し、6ヶ月後にv1〜v3を廃止
「廃止ポリシーがない」ことが最大の問題だった。ポリシーを明文化しただけで移行交渉がスムーズに進み、v4とv5の2バージョンに集約。保守専任エンジニアが不要になり、年間約1,200万円のコスト削減につながった。
状況: 社内マイクロサービス間のAPI（内部）と、パートナー企業向けAPI（外部）を同じURLパスバージョニングで管理。内部APIの変更のたびにバージョンが上がり、半年でv8に到達。
戦略変更:
- 外部API: URLパスバージョニングを継続。破壊的変更時のみバージョンアップ
- 内部API: バージョニングを廃止。代わりにコントラクトテスト（Pact）で互換性を自動検証
内部APIの変更リードタイムが平均5日→1日に短縮。外部APIはv2のまま18ヶ月安定稼働し、パートナーの信頼度が向上した。
やりがちな失敗パターン#
- バージョンを上げすぎる — 些細な変更のたびにバージョンを上げると、v1〜v10が並行稼働する地獄になる。破壊的変更以外はバージョンを上げない
- 廃止ポリシーなしにバージョンを増やす — 古いバージョンが永遠に残り、保守コストが雪だるま式に増える。リリース前に廃止スケジュールを決めておく
- 内部APIと外部APIを同じ戦略で管理する — 内部APIは頻繁に変更されるため、厳密なバージョニングは足かせになる。内部APIにはコントラクトテストで互換性を担保するアプローチが有効
- Deprecationの通知手段が不十分 — レスポンスヘッダーだけで廃止を通知しても、クライアントが気づかない。メール・ダッシュボード・Slackなど複数チャネルで通知する
まとめ#
APIバージョニングは 「変更の自由」 と「後方互換性」のバランスを取る技術。URLパスバージョニングをベースに、破壊的変更の判断基準を明確にし、廃止ポリシーを事前に定めておくことが成功の鍵。バージョンは増やすのは簡単だが、減らすのは難しい。だからこそ、計画的に管理しよう。