なぜAPIバージョン管理が必要か
APIは一度公開すると、多くのサードパーティアプリケーションや社内システムが依存します。機能改善・セキュリティ対応・設計の見直しによって既存の動作を変更する必要が生じたとき、バージョン管理の仕組みがなければすべての利用者のシステムが一斉に壊れる危険性があります。適切なバージョン管理によって、既存の利用者に影響を与えながら新しい機能を安全に提供できます。
APIバージョニングの方式
1. URLパスバージョニング（最も一般的）
バージョン番号をURLパスに含める方式です。
- 例：https://api.example.com/v1/users、https://api.example.com/v2/users
メリットは直感的でデバッグしやすく、ブラウザのアドレスバーやcurlコマンドで簡単に確認できることです。ほとんどのAPIゲートウェイでルーティング設定も容易です。デメリットはURLが「純粋なリソース識別子」でなくなることで、REST原則から外れるという意見もあります。実用性を重視する観点では最も広く採用されています。
2. リクエストヘッダーバージョニング
カスタムヘッダーにバージョンを指定する方式です。
- 例：Accept: application/vnd.myapi.v2+json
- 例：X-API-Version: 2
URLをクリーンに保てますが、curlやブラウザでのテストが手間になります。MicrosoftのREST API Guidelainesでも推奨されており、大規模なエンタープライズAPIで採用されています。
3. クエリパラメーターバージョニング
クエリパラメーターにバージョンを指定する方式です。
- 例：https://api.example.com/users?version=2
URLパスを変えずにバージョンを指定できます。ただし、クエリパラメーターはキャッシュの挙動に影響することがあります。
後方互換性を保つためのルール
新しいバージョンを発行せずに変更を加えられる「後方互換性のある変更」と、新バージョンが必要な「破壊的変更」を区別することが重要です。
後方互換性のある変更（マイナー・パッチ変更）
- 新しいオプショナルフィールドの追加（既存クライアントは無視できる）
- 新しいエンドポイントの追加
- 新しいオプショナルリクエストパラメーターの追加
- レスポンスのフィールドに新しい値の追加（enumの拡張）
破壊的変更（メジャーバージョンアップが必要）
- 既存フィールドの削除・名前変更
- フィールドのデータ型変更（string→integer等）
- 必須パラメーターの追加
- エンドポイントのURLの変更
- HTTPステータスコードの変更
- 認証方式の変更
API廃止（Deprecation）の進め方
古いバージョンのAPIを廃止する際は、利用者への影響を最小化するため段階的なプロセスが重要です。
- 廃止予告（Deprecation Notice）：廃止予定日を告知する。レスポンスヘッダーにDeprecationやSunsetヘッダーを追加して機械的に検知できるようにする
- 移行ガイドの提供：旧バージョンから新バージョンへの移行手順を詳細にドキュメント化する
- 移行支援期間の設定：最低6ヶ月から1年の移行期間を設ける
- 利用状況のモニタリング：旧バージョンのAPIトラフィックをモニタリングし、利用が続いているユーザーに個別連絡する
- 廃止実施：廃止日以降のリクエストに410 Goneを返すか、新バージョンにリダイレクトする
バージョニングの現場での設計パターン
パターン1：メジャーバージョンのみ管理
v1・v2のようなメジャーバージョンのみをURLに含め、マイナー変更は後方互換を保ちながら同一バージョン内に取り込む。最も一般的なパターンです。
パターン2：日付ベースバージョニング
Stripeが採用している方式で、2024-01-15のような日付をバージョンとして使います。「どの時点の仕様か」が明確でメジャーバージョンの意味が曖昧にならないメリットがあります。
まとめ
APIバージョン管理は「利用者との長期的な信頼関係」を保つための重要な仕組みです。最初からバージョニング戦略を設計に組み込み、後方互換性のルールを明確にし、廃止プロセスを丁寧に進めることで、利用者が安心してAPIを使い続けられる環境を提供できます。