API バージョニング (詳解)

API バージョニング詳解

API バージョニングの基本概念は「API バージョニング」を参照。ここでは実装パターンと移行戦略を詳しく解説する。

非破壊的変更の活用

バージョンアップを避けるため、非破壊的変更を優先する。

// v1 のレスポンス
{ "id": "123", "name": "Alice" }

// フィールド追加 (非破壊的): バージョンアップ不要
{ "id": "123", "name": "Alice", "email": "alice@example.com" }

// 既存クライアントは email を無視するだけ

Deprecation ヘッダー

Deprecation ヘッダーのコード例を示す。

// 旧バージョンに Deprecation ヘッダーを追加
if (version === '1') {
  return {
    statusCode: 200,
    headers: {
      'Deprecation': 'true',
      'Sunset': '2026-12-31',
      'Link': '</v2/users>; rel="successor-version"',
    },
    body: JSON.stringify(v1Response),
  };
}

移行のタイムライン

移行のタイムラインを図で示す。

Month 1: v2 をリリース、v1 に Deprecation ヘッダー追加
Month 2: v1 の利用状況をモニタリング
Month 3: v1 利用者に移行を通知
Month 6: v1 を廃止 (404 を返す)

GraphQL でのバージョニング

GraphQL はフィールドの追加が非破壊的で、クライアントが必要なフィールドを選択するため、バージョニングが不要になりやすい。@deprecated ディレクティブで非推奨フィールドを示す。

type User {
  id: ID!
  name: String @deprecated(reason: "Use firstName and lastName")
  firstName: String!
  lastName: String!
}

バージョニング戦略の比較

バージョニング戦略の比較を以下に示す。

戦略	方法	メリット	デメリット
URL パス	/v1/users	明確、キャッシュ可能	URL が変わる
ヘッダー	Accept: application/vnd.api.v1+json	URL が変わらない	発見しにくい
クエリパラメータ	?version=1	シンプル	キャッシュが複雑

基礎から学ぶなら関連書籍が手がかりになる。