APIバージョニング戦略入門｜URI・ヘッダー・クエリパラメータ型の違いとクラウドAPI設計での廃止計画ガイド

「今動いているAPIをバージョンアップしたいけど、既存のクライアントを壊したくない」——インフラエンジニアがクラウド移行に踏み出すと、こうしたAPI設計の悩みが必ず出てきます。

オンプレ時代は「イントラネット内だけのAPI」だったため、バージョン管理が曖昧でも何とかなっていました。しかしクラウド上でマイクロサービス化が進むと、複数チームが独立したペースでAPIを更新します。バージョニング設計が甘いと、一方のチームが変更した瞬間に別チームのサービスが壊れる——という事故が起こります。

この記事では、APIバージョニングの3つの主要パターン（URI・ヘッダー・クエリパラメータ）の違いと、AWS API Gatewayを使った具体的な実装方法、そして「古いバージョンをどう廃止するか」のサンセット設計まで、クラウドエンジニアの実務に直結する視点で解説します。

なぜAPIバージョニングが必要なのか？

オンプレ時代のシステムは、フロントエンドとバックエンドが同じリポジトリで管理され、リリースも一緒に行うことが多かったはずです。「APIが変わったらフロントも一緒に直す」が当たり前で、外部クライアントから呼ばれる機会も限られていた。

クラウドネイティブな構成では事情が変わります。

・マイクロサービス化: 複数のサービスが独立したAPIを持ち、それぞれ別のチームがデプロイする
・外部公開API: スマートフォンアプリやサードパーティが利用するため、突然の仕様変更ができない
・段階的移行: 新バージョンへの移行をクライアント側の都合に合わせてゆっくり進める必要がある

結果として「古いAPIと新しいAPIを同時に稼働させる期間」が必ず生まれます。この並走期間を安全に管理するための仕組みがAPIバージョニングです。

なお、REST API・GraphQL・gRPCそれぞれのAPI設計スタイルの使い分けについては、REST API vs GraphQL vs gRPC｜クラウドAPI設計の違いと用途別の選び方も参考にしてください。

APIバージョニングの3つの主要パターン

バージョン情報をどこに載せるかで、大きく3つのアプローチがあります。それぞれメリット・デメリットがあるため、状況に応じて選択します。

1. URIパス方式（/v1/users）

最も広く使われる方式です。URLにバージョン番号を含めるため、ブラウザのアドレスバーで見てすぐわかる、ログで追いやすい、CDNやロードバランサーでのルーティングが簡単といった利点があります。

# URIパス方式の例
GET https://api.example.com/v1/users       # バージョン1
GET https://api.example.com/v2/users       # バージョン2（レスポンス構造変更）

# AWS API Gatewayのステージとして実装する場合
GET https://{api-id}.execute-api.ap-northeast-1.amazonaws.com/v1/users

デメリットは「URLが変わるたびにクライアントのコード修正が必要になる」点です。また、厳密なRESTの考えでは「同じリソースに複数のURLが存在するのはおかしい」という意見もありますが、実務では利便性の高さから広く採用されています。AWS・Google・Stripeなどの主要クラウドAPIはほぼこの方式を使っています。

2. クエリパラメータ方式（?version=1）

URLのパス部分を変えず、クエリ文字列でバージョンを指定する方式です。

# クエリパラメータ方式の例
GET https://api.example.com/users?version=2

# AzureはAPIバージョンをクエリパラメータで統一管理
GET https://management.azure.com/subscriptions/{id}/resourceGroups?api-version=2024-03-01

Azureの管理APIは api-version パラメータを全エンドポイントで使っており、クエリパラメータ方式の大規模な実例です。パスが変わらないため既存URLへの後付けがしやすい一方、パラメータ省略時のデフォルト動作（最新版？エラー？）を明確に決めておく必要があります。

3. カスタムヘッダー方式（X-API-Version）

HTTPリクエストヘッダーにバージョン情報を含める方式です。URLが変わらないため「RESTの純粋主義」的には好まれますが、ブラウザのアドレスバーに見えないためデバッグが難しく、CDNやキャッシュの制御も複雑になります。

# カスタムヘッダー方式の例（curl）
curl -H "X-API-Version: 2" \
     -H "Authorization: Bearer {token}" \
     https://api.example.com/users

# Accept-Versionヘッダーを使うケースも
curl -H "Accept-Version: v2" https://api.example.com/users

社内向けのサービス間API（マイクロサービスのバックエンド間通信）で使われることがあります。外部公開APIにはキャッシュの扱いを含めたハードルが高いため、URIパス方式を優先するのが現実的です。

AWS API Gatewayでのバージョニング実装

Amazon API Gatewayの基本設定を押さえた後に、バージョン管理の設計を組み合わせるイメージです。AWS API Gatewayでバージョン管理を実装する方法は主に2つあります。

1. ステージを使ったバージョン管理

API Gatewayの「ステージ」機能を使って v1 / v2 を切り分ける方法です。デプロイ後にステージ名を付けることで、同じAPI設定から複数バージョンを同時に運用できます。

# AWS CLIでステージにデプロイ（AWS CLIコマンド）
aws apigateway create-deployment \
  --rest-api-id {api-id} \
  --stage-name v1

aws apigateway create-deployment \
  --rest-api-id {api-id} \
  --stage-name v2

# 各ステージのエンドポイント
# v1: https://{api-id}.execute-api.ap-northeast-1.amazonaws.com/v1/
# v2: https://{api-id}.execute-api.ap-northeast-1.amazonaws.com/v2/

運用上の注意点として、ステージ変数（Stage Variables）を活用すると、v1ステージは旧Lambda関数・v2ステージは新Lambda関数を向ける——といった柔軟な切り替えが可能です。Lambda関数のエイリアスと組み合わせることで、コード変更なしにバックエンドの切り替えができます。

2. カスタムドメイン + ベースパスマッピング

本番環境では、{api-id}.execute-api... という生のAPIエンドポイントではなく、api.example.com のような独自ドメインを使います。この場合、ベースパスマッピングでバージョンとステージを紐づけます。

# ベースパスマッピングの設定（AWS CLIコマンド）
# api.example.com/v1 → APIステージ「v1」
aws apigateway create-base-path-mapping \
  --domain-name api.example.com \
  --base-path v1 \
  --rest-api-id {api-id} \
  --stage v1

# api.example.com/v2 → APIステージ「v2」
aws apigateway create-base-path-mapping \
  --domain-name api.example.com \
  --base-path v2 \
  --rest-api-id {api-id} \
  --stage v2

この構成により、クライアントからは https://api.example.com/v1/users と https://api.example.com/v2/users の両方が使え、並走期間中も安全に移行を進められます。

新バージョンへの段階的な切り替えには、Blue/GreenデプロイとカナリアリリースのAWS実践ガイドで解説しているカナリア方式との組み合わせも有効です。

APIバージョンの廃止計画（サンセット設計）

バージョニングの「もう半分」がサンセット（廃止）設計です。古いバージョンを永遠に維持し続けるのはコストとリスクを招くため、廃止までの道筋をあらかじめ設計しておくことが重要です。

Sunset HTTPヘッダーの活用

RFC 8594で定義された Sunset ヘッダーは、そのAPIエンドポイントが廃止される予定日をレスポンスで通知する標準的な仕組みです。

# v1 APIのレスポンスヘッダーに廃止予定日を追加
# AWS Lambda関数のレスポンスで設定
HTTP/1.1 200 OK
Content-Type: application/json
Sunset: Sat, 01 Apr 2027 00:00:00 GMT
Deprecation: true
Link: ; rel="successor-version"

AWS Lambda関数のレスポンスに上記ヘッダーを追加することで、APIクライアントの開発者は「いつまでに移行すればよいか」を自動的に検知できます。

廃止までの4フェーズ

・Phase 1（発表）: 廃止日を6か月以上前に告知。ドキュメント・Sunsetヘッダー・開発者向けメールで周知
・Phase 2（警告）: 旧バージョンへのアクセスログをCloudWatchで監視し、まだ使っているクライアントを特定
・Phase 3（制限）: 廃止1か月前から旧バージョンのAPI Gatewayスロットリングを段階的に引き下げる
・Phase 4（廃止）: 廃止日以降は410 GoneまたはリダイレクトでAPIを終了

CloudWatchメトリクスで旧バージョンの呼び出し回数を監視し、「まだゼロにならない」状態が続いている場合は廃止の延長を判断します。API Gatewayのアクセスログをこまめに確認することで、想定外のクライアントを事前に発見できます。

よくあるミスと対処法

【ミス1】破壊的でない変更でもバージョンを上げてしまう

「変更のたびにバージョンを上げる」という運用をすると、v1～v10が乱立して管理が破綻します。バージョンを上げるのは破壊的変更（Breaking Change）が発生するときだけに限定するのが原則です。

フィールドの追加・オプションパラメータの追加は後方互換性があるため、バージョンを上げず同一バージョンに含めます。既存フィールドの削除・名前変更・型変更・必須化が破壊的変更の代表例です。

【ミス2】バージョンなしのエンドポイントから始める

「最初は /users だけで、後から /v1/users に変えよう」という後付け計画は失敗しやすいです。最初から /v1/ をパスに含める設計にしておくと、将来の移行コストが大幅に下がります。クライアントに「最初からバージョン付きのURLを使う習慣」を根付かせることが重要です。

【ミス3】Deprecationヘッダーを誰も見ていない

クライアント側のエンジニアがレスポンスヘッダーを確認していないと、廃止日を見逃します。SDKやAPIクライアントライブラリで Deprecation: true ヘッダーを検知してログ警告を出す仕組みを入れておくと、移行漏れを防ぎやすくなります。

【ミス4】廃止告知後に旧バージョンの監視をやめる

「廃止告知した」という安心から旧バージョンの監視を止めてしまい、廃止日当日に想定外のクライアントが多数いることに気づく——という事故は実際に起きます。廃止当日まで旧バージョンのアクセスログを監視し続け、ゼロに近いことを確認してから廃止処理を実行してください。

本記事のまとめ

APIバージョニングは「後から考えれば良い」ではなく、APIを公開する前の設計段階で決めておくべき基盤的な仕組みです。

・AWS API Gatewayではステージ機能とベースパスマッピングの組み合わせでバージョン管理を実装できる
・廃止計画（サンセット）は6か月以上前の告知とCloudWatchによるアクセス監視がセット
・バージョンを上げるのは破壊的変更のときだけ。後方互換性のある変更はバージョンアップ不要
・マイクロサービスへの移行が進むほど、バージョニング設計の重要性は高まる

APIバージョニングの設計をしっかり組んでおくことで、チーム間の「あのAPIが突然壊れた」騒動を大幅に減らすことができます。