api-versioning-strategy

API バージョニング戦略

サービスチームが、利用者に影響を与えずに API を進化させるための、長期にわたって一貫して適用できるルールを定めた完全な API バージョニング戦略ドキュメントを作成してください。このドキュメントでは、バージョニング方式の選定（根拠を含む）、導入から終了までのライフサイクルポリシー、破壊的変更の明確な分類、バージョンの非推奨化に際してチームが必要とするすべてのコミュニケーション資料を扱います。エンジニアがこのドキュメントを新しいチームメンバーや外部利用者に渡せば、何を想定すべきかを正確に理解できるようにしてください。

必須入力

以下の情報がまだ提供されていない場合は、確認してください。

• API の種類 — REST、GraphQL、または gRPC（それぞれバージョニングの仕組みが異なります）
• 現在のバージョニング方式 — URL パス（/v1/）、リクエストヘッダー、クエリパラメーター、またはなし。なしの場合は、ドキュメントをゼロから作成します
• 既存バージョン数とアクティブな利用者数 — ライフサイクルポリシーと移行範囲の規模を決めるために必要です
• 非推奨化のタイムラインに関する制約 — 厳守が必要な期限（契約上の SLA、コンプライアンス期間、年間リリースサイクルなど）
• 利用者の種類 — 社内チームのみ、外部パートナー、公開 API、またはその混在（コミュニケーションチャネルの選定に影響します）

入力情報が不足している場合は、ドキュメントを作成する前に質問してください。GraphQL の場合、バージョニングの方式は大きく異なり、バージョニングではなくスキーマの進化を中心とするため、それに応じて方式のセクションを調整してください。

出力形式

---

API バージョニング戦略：[Service Name]

担当者： [Team Name] API の種類： [REST / GraphQL / gRPC] ドキュメントバージョン： 1.0 最終レビュー日： [Date] 次回レビュー日： [Date + 6 months]

---

1. バージョニング方式

選択した方式：[URL Path / Request Header / Query Parameter]

方式	例	メリット	デメリット	判定
URL パス	/v2/orders	ログやブックマークで確認しやすい。ルーティングも簡単です	厳密な REST のリソース識別に反します。URL 空間が煩雑になります	外部向け REST API に推奨
Accept ヘッダー	Accept: application/vnd.[service].v2+json	URL をすっきり保てます。適切なコンテンツネゴシエーションが可能です	ブラウザーでのテストが難しく、ログでも目立ちにくいです	クライアントを管理できる内部 API に推奨
クエリパラメーター	/orders?version=2	URL の構造を変更せずに簡単に後付けできます	クライアントコードで見落とされがちです。キャッシュキーに関する問題もあります	すでに本番稼働している読み取り中心の API に限り許容
GraphQL スキーマの進化	フィールドの非推奨化と @deprecated ディレクティブ	追加的な変更にバージョニングは不要です	規律あるスキーマ設計が必要です	GraphQL API に推奨

[chosen scheme] を選択した根拠： [この方式が、提示された API の種類、利用者の種類、運用状況に適している理由を説明する段落。具体的な入力を参照してください。例：「この API は生成クライアントを通じて連携する外部パートナーが利用するため、URL パスによるバージョニングが最も予測しやすいルーティング動作を実現し、ヘッダーのネゴシエーションの複雑さをなくします。」]

バージョン形式

[Base URL]/v{MAJOR}/{resource}

Examples:
  https://api.[company].com/v1/orders
  https://api.[company].com/v2/orders/{id}/items

Version identifier: integer only (v1, v2, v3)
No minor versions in the URL — minor/patch changes are non-breaking and deployed continuously.

---

2. バージョンのライフサイクルポリシー

ライフサイクルの段階

  STABLE ──────────────────────────────────────────────────►
      │
      ├─ STABLE        Active development, full SLA, new consumers allowed
      │
      ├─ DEPRECATED    Announced, timeline posted, migration docs live.
      │                New consumers blocked. Existing consumers receive warnings.
      │
      ├─ SUNSET        Requests return HTTP 410 Gone + migration pointer.
      │                30-day window before routing is removed.
      │
      └─ RETIRED       Routing removed, docs archived, no traffic accepted.

段階	期間	SLA の適用	新規利用者の受け入れ	必要な対応
安定版	次のバージョンに置き換えられるまで	あり — 完全に適用	あり	なし
非推奨	[12 months / adjust per constraint]	あり — 低下を許容	なし	サンセット日までに移行
サンセット	30 日間	ベストエフォートのみ	なし	直ちに移行
廃止	恒久	なし	なし	—

安定版の最短期間： バージョンは、非推奨化を告知する前に、少なくとも [6 / 12] か月間は安定版として維持する必要があります。

同時に提供するバージョンの上限： 安定版または非推奨のステータスにあるバージョンは、同時に [2] 個を超えてはなりません。v3 をリリースする場合は、同じ告知内で v1 のサンセット日を設定する必要があります。

---

3. 破壊的変更と非破壊的変更の分類

API を変更する前に、必ずこの表を適用してください。変更が破壊的と分類された場合、新しいメジャーバージョンが必要です。判断に迷う場合は、破壊的と分類してください。

変更の種類	具体例	分類	理由
レスポンスフィールドの削除	レスポンスから order.legacy_id を削除する	Breaking	このフィールドを読み取るクライアントで null ポインターが発生するか、処理が失敗します
フィールド名の変更	user_name → username	Breaking	古い名前を参照するクライアントは null を受け取ります
フィールド型の変更	"amount": "10.00" → "amount": 10.00	Breaking	デシリアライズ時に型が一致しません
任意フィールドを必須に変更	POST ボディで email を必須にする	Breaking	指定を省略していた既存の呼び出し元は 400 を受け取ります
エンドポイントの削除	DELETE /v1/widgets/{id} を削除する	Breaking	既存の呼び出し元は 404 を受け取ります
HTTP メソッドの変更	GET /search → POST /search	Breaking	ブックマーク済み、またはキャッシュされた GET 呼び出しが失敗します
認証方式の変更	API キー → OAuth2	Breaking	すべてのクライアントで再認証が必要になります
エラーレスポンスの構造変更	エラー JSON スキーマを変更する	Breaking	エラー処理コードがレスポンスを誤って解析します
列挙値の追加（レスポンス）	新しい status: "on_hold" の値を返す	Breaking	デフォルト処理のない switch 文では、どのケースにも該当せず処理が続行されます
ページネーションのデフォルト値の変更	page_size のデフォルト値を 20 → 50 にする	Breaking	レスポンスの長さが予期せず変わります
入力検証の厳格化	最大長を 100 → 50 にする	Breaking	以前は有効だった入力が拒否されます
レスポンスへの新しい任意フィールドの追加	order.tax_breakdown を追加する	非破壊的	仕様に従い、クライアントは未知のフィールドを無視します
新しい任意リクエストパラメーターの追加	?include_archived=true を追加する	非破壊的	既存のクライアントはこれを無視します
新しいエンドポイントの追加	GET /v1/orders/{id}/audit	非破壊的	既存のクライアントから参照されていません
入力検証の緩和	最小長を 10 → 5 にする	非破壊的	既存の有効な入力は引き続き有効です
パフォーマンスまたはレイテンシの改善	レスポンス時間の短縮	非破壊的	—
新しい列挙値の追加（リクエストのみ）	新しい type: "express" を受け入れる	非破壊的	既存の値も引き続き受け入れられます

---

4. 非推奨化のプロセス

非推奨化のチェックリスト（手順）

• T-0（決定日）： エンジニアリングリードが非推奨化を承認します。新しいバージョンが Stable であることを確認します。廃止日を設定します。
• T-0： API ドキュメントを更新し、すべての v[N] エンドポイントページに非推奨のバナーを追加します。
• T-0： すべての v[N] レスポンスに Deprecation および Sunset レスポンスヘッダーを追加します（以下の形式を参照）。
• T-0： API ゲートウェイと開発者ポータルで、v[N] の新しい利用者登録をブロックします。
• T-0： 登録済みのすべての利用者に、最初の非推奨通知を送信します（セクション 5 のテンプレートを参照）。
• T-0： エンジニアリングのバックログに追跡用のイシューを作成し、把握済みのすべての利用者とその移行状況を紐付けます。
• T マイナス 30 日： 引き続き v[N] のトラフィックを送信しているすべての利用者に、30 日前の警告を送信します。
• T マイナス 7 日： 最終警告を送信します。利用者のトラフィックが 1 日あたり 100 件を超える場合は、そのエンジニアリングリードに直接エスカレーションします。
• 廃止日： v[N] のルーティングを切り替え、移行ガイドへのリンクを本文に含む HTTP 410 Gone を返すようにします。
• T プラス 30 日： ルーティングルールを削除します。ドキュメントをアーカイブします。追跡用イシューをクローズします。

非推奨化レスポンスヘッダー

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
Link: <https://docs.[company].com/api/migration/v1-to-v2>; rel="successor-version"

廃止時のレスポンス本文

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": "api_version_sunset",
  "message": "API v1 was sunset on 2027-01-01. Please migrate to v2.",
  "migration_guide": "https://docs.[company].com/api/migration/v1-to-v2",
  "support": "api-support@[company].com"
}

---

5. クライアントへの通知テンプレート

最初の非推奨通知

Subject: [Action Required] [Service Name] API v[N] Deprecation — Sunset [Date]

Hi [Team / Partner Name],

We are deprecating [Service Name] API v[N], effective [Sunset Date].

What this means for you:
- v[N] continues to work normally until [Sunset Date]
- After [Sunset Date], all v[N] requests return HTTP 410 Gone
- v[N+1] is available today and fully stable

Your current usage: approximately [X] requests/day as of [Date].
Estimated migration effort: [Small: < 1 day | Medium: 1–3 days | Large: 3–10 days]

Migration resources:
  Migration guide:  [URL]
  Changelog:        [URL]
  Office hours:     [Date/Time/Link]
  Support:          [Slack channel or email]

Key dates:
  [Date]          Deprecation announced (today)
  [Date]          New consumer onboarding blocked for v[N]
  [Date]          30-day warning sent to remaining consumers
  [Sunset Date]   v[N] returns 410 Gone

Reply to this message or contact us at [channel] with questions.

[Your Name], [Team Name]

30 日前の警告

Subject: [30 Days Remaining] [Service Name] API v[N] sunsets [Date]

Hi [Team / Partner Name],

[Service Name] API v[N] sunsets in 30 days on [Date].

Your current v[N] traffic: [X] requests/day — migration is not yet complete.

If you have a technical blocker requiring an extension, contact us before
[Date minus 14 days]. Extensions require a documented blocker and a committed
migration completion date.

Migration guide: [URL] | Support: [channel]

---

6. 移行ガイドのテンプレート

バージョン移行ごとに、docs.[company].com/api/migration/v[N]-to-v[N+1] に移行ガイドを公開します。

# Migration Guide: v[N] → v[N+1]

**Estimated effort:** [Small: < 1 day | Medium: 1–3 days | Large: 3–10 days]
**Breaking changes in this guide:** [count]

## Quick Start

Update your base URL:
  Before: https://api.[company].com/v[N]/
  After:  https://api.[company].com/v[N+1]/

## Breaking Changes

### 1. [Field Rename: user_name → username]

**Affected endpoints:** `GET /users/{id}`, `POST /users`

Before (v[N]):
{ "user_name": "alice" }

After (v[N+1]):
{ "username": "alice" }

Migration: Replace all references to `user_name` with `username` in request
builders and response parsers.

### 2. [Next breaking change — repeat structure]

## New Capabilities in v[N+1]

| Feature | Description | Docs |
|---------|-------------|------|
| [Feature name] | [Brief description] | [Link] |

## SDK Upgrade Reference

| Language | Package | v[N+1] Version | Install Command |
|----------|---------|----------------|-----------------|
| Python | `[company]-sdk` | `2.0.0` | `pip install [company]-sdk==2.0.0` |
| Node.js | `@[company]/sdk` | `2.0.0` | `npm install @[company]/[email protected]` |
| Go | `github.com/[company]/sdk-go` | `v2.0.0` | `go get github.com/[company]/sdk-go/v2` |
| Java | `com.[company]:sdk` | `2.0.0` | Update pom.xml / build.gradle |

## Migration Validation Checklist

- [ ] Base URL updated to v[N+1]
- [ ] All renamed fields updated in request serializers
- [ ] All renamed fields updated in response deserializers
- [ ] Error-handling code updated for new error shape
- [ ] Integration tests passing against v[N+1] in staging
- [ ] Load test completed against v[N+1] — latency within acceptable range
- [ ] Rollback plan documented if issues arise post-cutover

---

7. バージョン固有のドキュメント

• 安定版と非推奨バージョンそれぞれに、個別のドキュメントページを用意します。
• 非推奨バージョンのドキュメントには、次のバナーを常時表示します：「このバージョンは非推奨です。サポート終了日：[Date]。[v[N+1] に移行]。」
• OpenAPI 仕様、Protobuf 定義、または GraphQL スキーマにはタグを付け、リポジトリ内の /api/v[N]/ 以下にバージョンごとにアーカイブします。
• ルートレベルの CHANGELOG.md に、すべての破壊的変更と非破壊的変更をバージョンごとに記録します。コミット履歴に埋もれさせてはいけません。

---

8. SDK のバージョン整合性

API バージョン	SDK メジャーバージョン	SDK GA 日	SDK EOL 日
v[1]	1.x	[Date]	[API Sunset + 90 days]
v[2]	2.x	[Date]	Active

• SDK のメジャーバージョンは、API のメジャーバージョンと 1 対 1 で対応させます。
• SDK のマイナーバージョンは、非破壊的な API の追加に合わせます。
• SDK の EOL 日は API のサポート終了日から 90 日後とし、利用者に移行のための猶予期間を追加で確保します。
• 基盤となる API バージョンが非推奨になった際、SDK は実行時に非推奨警告のログを出力します。

---

戦略の作成者：[Team Name] — 質問はこちら：[Slack channel or email]

---

アンチパターン

• 列挙型の拡張（新しいレスポンス値の追加）を非破壊的変更に分類しないでください。網羅的な switch 文を使用するクライアントは、予期しない列挙値を受け取ると動作しなくなります。
• 最大規模の利用者にとって実現可能か確認せずに、サポート終了日を設定しないでください。利用者が法的な期限に間に合わなくなるようなサポート終了は、無視されたり、エスカレーションされたりします。
• 安定版／非推奨バージョンを 2 つより多く同時に維持しないでください。サポート対象のバージョンが 1 つ増えるごとに、保守の負担と利用者の混乱が増大します。
• すべての利用者の移行完了を把握する唯一の手段として「トラフィックを監視する」を使わないでください。利用者を個別に特定し、移行の完了状況を明示的に追跡してください。
• 移行ガイドを省略しないでください。作業量を見積もった段階的なガイドがなければ、利用者は移行をいつまでも先延ばしにします。

品質チェック

• バージョン管理方式の推奨には、提示された API の種類と利用者の種類に結び付いた明確な根拠が含まれています。一般論だけの推奨ではありません。
• 破壊的変更の表には、少なくともフィールドの削除、フィールド名の変更、型の変更、任意フィールドの必須化、エンドポイントの削除、列挙型の拡張、デフォルト値の変更が含まれています。
• 非推奨化のタイムラインには具体的な期間が記入されており、抽象的なプレースホルダーのまま残されていません。
• 3 つのコミュニケーション資料がすべて揃っています。最初の非推奨通知、30 日前の警告、移行ガイドのテンプレートです。
• サポート終了のレスポンスヘッダー（Deprecation、Sunset、Link）には、正しい RFC 日付形式と実際の URL 構造が使用されています。
• SDK のバージョン整合性を示す表があり、SDK のメジャーバージョンと API のメジャーバージョンの対応が明記されています。
• 同時にサポートするバージョンの最大数が具体的な数値で記載されています。