APIバージョニング戦略

バージョン管理が必要な理由

APIはクライアントよりも高速に変更されます。バージョン管理を使用すると、統合を破ることなく、機能をリリースしたりエラーを編集したり、変更の儀式を設定したり、進化を予測できます。キー：デフォルトの添加物の変更、メジャー-破損のみ、自動互換性チェック、思慮深い日没ポリシー。

基本的な原則

1.Additive-first：新しいオプションフィールド/メソッド/イベント-ok；削除と意味の変更-メジャー。
2.MGC（最低保証契約）は安定しています；enrichment-capabilities/'を通じて？include='。
3.Tolerant reader：クライアントは未知のフィールドを無視し、enum extensionsを正しく生き残ります。
4.セマンティックバージョニング：'MAJOR。マイナー。アーティファクト、SDK、イベントのPATCH。
5.自動化：schema-diff、 linters、およびCDCテストは、変更の破損をブロックします。

バージョンを保存する場所（アドレス力学）

REST/HTTP

URIバージョン：'/v1/orders'→ルーティングが簡単で、ゲートウェイで便利です。マイナス-アイデアの進化を「曖昧にする」。
メディア/ヘッダー：'Accept： application/vnd。例を示します。注文します。v1+json'-正確なフォーマット制御；だまされにくい。
クエリのバージョン：'？api-version=1'-A/Bに便利ですが、キャッシュ/ログで簡単に失うことができます。
推奨事項：主要行のURI+機能/機能フラグ、マイナー拡張のコンテンツネグレーション。

gRPC/Protobuf

パッケージ/サービス：'パッケージ支払い。v1；サービスPaymentsV1；'-明示的な行。
タグの番号付けは変更されません。削除されたタグは再利用できません。
新しいフィールド-'optional'；breaking→new '。v2'。

GraphQL

URLに明示的なメジャーを持たないスキーマ。@deprecatedおよび移行ウィンドウによる進化；「real」 majorは新しいエンドポイントスキームです。
制御の複雑さ/深さは契約の一部です。

イベントドリブン（Kafka/NATS/Pulsar）

イベント名：'支払い。承認されました。v1'はタイプのバージョンです。
互換モード（BACKWARD/FORWARD/FULL）を持つスキーマレジストリ（Avro/JSON Schema/Protobuf）。
移行期間のメジャー→デュアルエミット'v1'および'v2'。

バージョンモデルと変更ポリシー

セマンティックバージョニング

MAJOR-改変：フィールドの削除/名前変更、メンバーシップキーの変更、ステータスの意味の異なる、検証の締め付け。
MINOR-additive：新しいオプションフィールド/エンドポイント/イベント、tolerant-readerの新しい列挙値。
PATCH-コントラクトとセマンティクスを変更せずに修正します。

デプロイ&サンセット

HTTP-ヘッダー'Sunset'、 'Deprecation'；イベント-別個の'。deprecation。「お知らせ」

廃止されたマーク（'Deprecated： true'、'@deprecated'）、日没の日付、代替および移行ガイドを公開します。
削除するかどうかを決定するテレメトリ使用法。

スタイル別のバージョン戦略

REST（休息）

/v1 、/v2の主要な行。
MINOR：スキーマ拡張、'？fields='、'？include='；enum extensionsを保護します。
ETag/If-Matchとidempotent POSTは、破損しない整合性を確保します。
エラー-安定したフォーマット（'type'、 'code'、 'trace_id'）。

gRPC

決済のための新しいサービス/メソッドを紹介します：'PaymentsV2。キャプチャ'。
エラーステータスと期限セマンティクスは契約の一部です。変更→新しい方法/サービス。
ストリーミング：メッセージ注文に同意し、マイナーに変更しないでください。

GraphQL

フィールドとタイプを自由に追加します。削除-'@deprecated'+マイグレーションウィンドウ；大きな再設計→新しいスキーム（'/graphql-v2'）

イントロスペクションと説明-お客様の移行に必須です。

イベント情報

コアと濃縮：コアは安定しており、近くに住んでいて、別々にバージョン管理されています。
パーティションキーはメジャーライン内で変更されません。
主要な移行-'dual-emit'+投影/消費者移行。

ネゴシエーションとケーパビリティフラグ

機能：クライアントが'X-Capabilities： risk_score,price_v2'を送信します。サーバーは拡張ビューで応答します。
（HTTP）と部分応答のヒントを好みます。
ソケット/ストリーム-サポートされている拡張子のリストを持つハンドシェイクメッセージ。

痛みのないメジャーバージョンのリリース

1.RFC/ADR：なぜメジャーが必要なのか、何が壊れるのか、リスクマトリックス。
2.デュアルラン：'v1'と'v2'の並列起動（ダブルイベントパブリッシング、2つのゲートウェイルート、トラフィックミラーリング）。
3.マイグレーションアダプタ：重いクライアントの'v1↔v2'プロキシ/トランスレータ。
4.カナリア：ゲートウェイの顧客グループ/トピック/タグ。
5.日没の計画：日付、コミュニケーション、立場、テストデータ、使用法の監視。

プラットフォームとインフラストラクチャの役割

APIゲートウェイ/サービスメッシュ：バージョン、ヘッダ、パスによるルーティング；rate-limitバージョンあたりの認証。
スキーマレジストリとカタログ：拡散履歴を持つ仕様/スキームの真実のソース。
CI/CD： Spectral、 Buf、 schema-diff （OpenAPI-diff、 Buf breaking）、 CDC （Pact）。
オブザベーション：バージョンはlogs/trails/metricsに含める必要があります。

バージョンテスト

PRのSchema-diff：ブロックの分割。
消費者主導の契約：プロバイダーは実際の消費者契約に対してテストされます。
ゴールデンサンプル：バージョンへの参照応答。
E2E canary： p95/p99の比較、バージョン間のエラーとタイムアウト。
イベントのリプレイ：投影は矛盾なくv2に再構成されます。

データとデータベースの移行

REST/gRPCの場合：データベースのマイグレーションはexpand-and-contract（列の追加→書き込み開始→スイッチの読み込み→古い削除）によって調整されます。
イベントの場合：デュアルエミットと消費者の移行；時々-新しい投影にログを再生します。
「大きな爆発」をしないでください-ロールバックでステップに分割。

セキュリティ関係

バージョンごとのスコープ：v1/v2の個々のOIDCスコープ/ロール。
トークンの秘密/クレームは契約の一部です。彼らの変化=メジャー。
PII/PCI-不必要にペイロードを拡張しないでください。新しいフィールド-最小限の権限を持つ。

アンチパターン

Swagger-wash：仕様が更新され、サーバーが更新されません（またはその逆）。
protobufタグの再利用はデータの静かな破損です。
メジャーなしでenumの意味を変更します。
グローバル'/v2'「化粧品のために」：破損の事実のないバージョン。
sunset/usageのメトリックを忘れました：古いバージョンを安全に削除することは不可能です。
異なるメジャーのための1つの一般的なトピック：注文とキーの混合。

プレリリースのチェックリスト

• 変更は添加剤または別の主要ラインが用意されています。
• Linterとschema-diffは緑色です（クロールしませんでした）。
• SDK/examples/documentation、 compatibility footnotesを更新しました。
• クライアントの許容リーダーを有効にしました。enum-fallbackテスト済み。
• メジャー-デュアルランプラン、アダプター、カナリア、日没の日付と郵送。
• メトリック/ログ/トレイルには、バージョンとセグメンテーションが含まれています。
• v1↔v2を比較するためのスタンドとゴールデンセットがあります。
• イベントの場合、スキーマレジストリはBACKWARD/FULLモードで、パーティションキーは変更されません。

サンプルテンプレート

REST （URI+ネゴシエーション）

ルート： '/api/v2/orders/{ id}'

［優先］： 'include=items、 customer'、 'X-Capabilities： risk_score'

廃止： 'Sunset： 2026-06-30'、 'Link： ；rel=「代替」'

Protobuf/gRPC

proto package payments.v2;

service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}

イベント情報

支払いだよ。キャプチャされた。v2'（中心）および'支払。豊かになりました。v2'（詳細）。
移行期間については、プロデューサーは'v1'と'v2'になります。

FAQ（よくある質問）

正確に'/v2'が必要なのはいつですか？
不変量/セマンティクスが変化すると、フィールド/メソッドが削除され、識別子の形式、パーティションキー、SLA/タイミングが変化してクライアントが壊れる。

RESTで明示的なバージョンなしで生活できますか？
小規模なシステムの場合のみ。外部統合の場合、明示的な主線の方が優れています。

どのくらい古いバージョンを維持するには？
生態系によって異なります。外部パートナーの場合、早期通知とカナリアで通常6〜12ヶ月。

イベントバージョニングとAPIの違いは？
イベント-追加のみ；new semantics=new type '。v2'とdual-emit。パーティションキーは契約の一部です。

［結果］

バージョン管理戦略は、プロセスとツールです。デフォルトの追加進化、明確な主要ライン、機能ネゴシエーション、デュアルラン、日没です。自動的な互換性チェック、使用テレメトリー、ドキュメンテーションの規律を追加すると、APIは「夜間移行」や顧客の予期しない低下なしに迅速に進化します。