HTTPメソッドとAPIバージョニング戦略

APIバージョニングが重要な理由

APIのリクエストまたはレスポンスフォーマットを変更すると、既存のクライアントが壊れる可能性があります。バージョニングにより、後方互換性を維持しながらAPIを進化させることができます。

バージョニング戦略

1. URLパスバージョニング

GET /api/v1/users/42 HTTP/1.1
GET /api/v2/users/42 HTTP/1.1

利点： 明示的、ルーティングが容易、テストが容易 欠点： エンドポイントが重複、REST純粋主義者のリソースIDの原則に反する

2. ヘッダーバージョニング

GET /api/users/42 HTTP/1.1
Accept: application/vnd.example.v2+json

利点： クリーンなURL、コンテンツネゴシエーション 欠点： ブラウザでのテストが困難、発見しにくい

3. クエリパラメータバージョニング

GET /api/users/42?version=2 HTTP/1.1

利点： シンプル、切り替えが容易 欠点： CDNがクエリパラメータを無視するとキャッシュが不正確になる可能性

メソッドとバージョニングの相互作用

シナリオ	影響
POSTボディの新フィールド	オプションなら非破壊的；必須なら破壊的
GETレスポンスからのフィールド削除	破壊的変更 — 新バージョンが必要
PUTをPATCH必須に変更	破壊的変更 — 新バージョンが必要
PATCHサポートの追加	非破壊的な追加
ステータスコードの変更	潜在的に破壊的

メソッド固有のバージョニングのヒント

GETレスポンス — 追加的な変更を使用。新フィールドの追加は非破壊的。フィールドの削除やリネームには新バージョンが必要。

POST/PUTボディ — 新しいオプションフィールドは非破壊的。新しい必須フィールドは破壊的。不明なフィールドを適切に検証（無視 vs 拒否）。

DELETE動作 — ハード削除からソフト削除への変更は非破壊的（いずれの方法でもリソースは消える）。レスポンスボディのフォーマット変更はレスポンスを解析するクライアントを壊す可能性がある。

Deprecationヘッダー

HTTP/1.1 200 OK
Deprecation: Sun, 01 Jul 2026 00:00:00 GMT
Sunset: Sun, 01 Jan 2027 00:00:00 GMT
Link: </api/v3/users>; rel="successor-version"

Deprecationヘッダーはエンドポイントが削除されることをクライアントに警告し、Sunsetは正確な削除日を指定します。