バージョニングと互換性

🐱 この章の目次

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

公開 API は一度リリースするとクライアントが依存するため、破壊的変更を自由に加えられません。 後方互換性（backward compatibility） を維持しながら API を進化させるために、バージョニング戦略が必要です。 DDIA 第 4 章で扱うエンコーディングとスキーマ進化の考え方は、API 設計にもそのまま適用されます。

バージョニング戦略

代表的な戦略は以下の 3 つです。

戦略	例	メリット	デメリット
URL パス	`/v1/users`	明示的で分かりやすい	URL が変わるためキャッシュ・ブックマークに影響
カスタムヘッダー	`API-Version: 2`	URL を汚さない	ブラウザやツールで扱いにくい
Accept ヘッダー	`Accept: application/vnd.api+json;version=2`	HTTP 標準に則る	複雑で実装コストが高い

URL パスによるバージョニングが最も広く採用されており、初期段階ではこの方式を推奨します。

後方互換な変更と破壊的変更

以下は後方互換な（非破壊的な）変更です。

レスポンスにオプショナルフィールドを追加する
新しいエンドポイントを追加する
クエリパラメータにオプショナルな項目を追加する

以下は破壊的変更です。

既存フィールドの型やセマンティクスを変更する
必須フィールドを追加する
エンドポイントの URL を変更・削除する

クライアントは「知らないフィールドは無視する」という原則（寛容な読み取り）を採用することで、非破壊的変更に対して堅牢になります。

非推奨化（Deprecation）

フィールドやエンドポイントを廃止する際は、段階的に 非推奨化（deprecation） を進めます。 OpenAPI では deprecated: true を指定することで、ドキュメント上に警告を表示できます。

paths:
  /v1/legacy-endpoint:
    get:
      deprecated: true
      summary: "[非推奨] 旧形式のデータ取得"
      description: "v2/new-endpoint を使用してください。2025-12 に削除予定。"

実行時には Sunset ヘッダー（RFC 8594）で廃止日をクライアントに通知し、移行猶予期間を設けます。

スキーマ進化と互換性ルール

API スキーマの進化は、DDIA 第 4 章で解説されるエンコーディングの前方・後方互換性と本質的に同じ問題です。 Protobuf のフィールド番号のように、各フィールドに一意の識別子を持たせ、新旧スキーマが共存できるよう設計します。 OpenAPI の CI パイプラインにスキーマ差分チェック（例: oasdiff）を組み込むことで、破壊的変更を自動検知できます。

# oasdiff で破壊的変更を検出
oasdiff breaking base.yaml revised.yaml