APIの互換性と更新

1）互換性の基礎

Additive-first：新しい値（新しいオプションのフィールド/エンドポイント、新しい列挙値）を壊さずに追加します。
安定した契約：「仕様で約束されているものは動作します。」文書化された行動。
後方>前方：後方互換性の優先順位；forwardは寛容な読者によって許可されます。
ドキュメントはプライマリです：真実の唯一のソースは、スキーム（OpenAPI/AsyncAPI/Proto）のレジストリ・バージョンです。
Explicit evolution： breaking-新しいメジャーバージョンと移行ガイドのみ。

2）変更の分類

2.1多用性がある（MINOR/PATCH）

オプションのフィールド/ヘッダー、新しいエンドポイント、デフォルトのクエリパラメータを追加します。
制限（'page_size'、 TTL）を増やし、コード/セマンティクスを変更せずにエラーを明確にします。
クライアントが"unknown' （tolerant-reader）を無視した場合、列挙値を追加します。

2.2あいまい（行動）

デフォルトの変更、並べ替え、薄いタイムアウト、クォータ-ビジネスロジックを「壊す」ことができます。RFC+アナウンスとカナリアが必要です。

2.3ブレイキング（MAJOR）

フィールドの名前変更/削除、タイプ/フォーマットの変更、エラーコードの置き換え、契約/認証スキームの非互換性の逆転。

3）バージョン管理ポリシー

戦略：'path versioning' （'/v1'、'/v2'）。
マイナー/パッチ：「add、 don 't break」。
日付付きヘッダ（オプション）：「X-API-Version-Date」（ソフトインクリメンタル変更用）。
メディアタイプ（Op。）： 'Accept： application/vnd。アクメだよ。細かい造粒のためのv1+json'。

4）廃止と日没

4.1コミュニケーションヘッダー

Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"

4.2出金注文

1.ポータル/メーリングリスト/SDKリリースノートでのお知らせ。
2.警告ウィンドウは90〜180日≥ます。
3.採用ダッシュボードのステータス。
4.日没後-410 Goneまたは「読み取り専用」モードの猶予期間、合意された場合。

5）バージョンの移行と共存

二重書き込み/二重読み取りの遷移とレポートとの和解。
アダプター（一時的な）：古いペイロードのゲートウェイ変換→新しいスキーム；アダプターの寿命は限られています。
SDKヘルプ：両方のバージョンをサポートしているリリースで、減衰警告が表示されます（1プロセスあたり1回）。
フィーチャーフラグ：キー/テナントのリストに従って新しい意味を含める。

6）後方および前方両立性

6.1後方（古いクライアント↔新しいサーバー）

型式を変更しない/必須。
新しいフィールドはオプションのみです。
エラー-古い'error_code'、新しいコードを追加、置き換えないでください。

6.2 Forward（新しいクライアント↔古いサーバー）

'OPTIONS '/'/versions'で機能をチェックします。
優美な振る舞い：クライアントは欠落している機能に寛容でなければなりません。

7）契約および自動点検

レジストリ：スキーマバージョンを保存します。PRは→breaking/non-breakingレポートを掘ります。
Linter：名前/タイプ、idempotency、ページネーション、安定したコード。
CDC （Consumer-Driven Contracts）：サプライヤのCI （Pactとアナログ）でインテグレータをテストします。
ゲートトajor bump/RFCなしで破断するとPRがブロックされます。

yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml

8）カナリア延長および逆

カナリア： トラフィックの10％→25％→50％→100％；SLO劣化時の自動ロールバック（5xx/latency/429）

ベータキー：allowlistによる新しいバージョンへのアクセス。
放出の凍結：燃焼の間の間違い予算。
Acceptance analytics：新しいバージョンでのトラフィック/クライアントの共有、移行時間。

9）詳細な互換性： エラー、ペジネーション、idempotence

9.1エラー

既存のスクリプトのHTTPステータスを変更しないでください。
'error_code'-stable；新しいコードは追加のみです。
'application/problem+json'は単一のフォーマットです。

9.2ページネーション

古い'offset/limit'がサポートされている場合は、cursor/keyset=MINORに切り替えます。
ソート'（updated_at,id）'とカーソルの安定性を文書化します。

9.3 Idempotency

write-'Idempotency-Key'+'409 IDEMP_REPLAY'競合の場合。
マイグレーションは、idempotencyのセマンティクスを変更するべきではありません。

10）ゲートウェイ変換（適切な場合）

v1→v2フィールドをマップし、エラーを正規化し、日付/マネーフォーマットを変換します。
ガードレール：変換は透明でロギング可能です。壊れることを隠さないで、時間限られた橋として使用して下さい。

11）コミュニケーションとポータル

Changelog （'added/changed/deprecated/removed/fixed'）。
バージョンカード：ステータス（ベータ/GA/非推奨）、日没日、ガイドへのリンク。
通知webhook：'非推奨。notice'、'version。'、'プランをリリースしました。「変更」。
SDKリリースノート+ポータルバナー。

12）成功指標

採用率v2（リクエスト/クライアントごと）。
後方コンパットインシデント。
リリース前/リリース後のエラーミックス（4xx/5xx/429 shares）。
Time-to-Adoptの中央値。
サポート負荷（チケット/週）。
費用対効果。

13）テンプレートと例

13.1バージョンタイトルとデクリメント

X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"

13.2バージョンポリシー（YAMLフラグメント）

yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]

13.3 OpenAPI Field Append互換性

yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive

14）リリースチェックリスト（MINOR/MAJOR）

MINOR（マイナー）

• DIFF：非破壊、リンターグリーン
• ドキュメント/SDK更新（例/コーデック）
• Canary+auto-SLOロールバック
• Commプラン、ポータルページ
• ダッシュボードの採用とエラー

MAJOR

• RFC/ADR、日没日と≥ 90ウィンドウ-180日
• ブリッジと移行ガイドのv1↔v2
• 二重書き込み/読み取りと和解
• 両方のAPI+アラートを持つSDK
• キーインテグレータによるパイロット

15）実施計画（3つの反復）

1.基金（2週間）：

CIのスキーム、リント、自動差分のレジストリ；互換性ポリシー；'Deprecation/Sunset'のタイトル。

2.マネージドリリース（3〜4週間）：

カナリア、フィーチャーフラグ、SLOアラート;バージョンポータル；2つのブランチをサポートしたSDKリリース。

3.自動化とスケール（連続）：

CIの消費者のCDCテスト、採用動向の日没予測、自動通知とリマインダー。

16） ミニFAQ

メジャーなしでフィールドタイプを変更できますか？
いいえ、そうではありません。「ストロカ→チスロ」でも壊れています。新しいフィールドを入力すると、古いフィールドは非推奨になります。

Enum：値を追加できますか？
はい、クライアントが寛容な読者である場合。それ以外の場合-最初のアラートとベータ版。

古いバージョンを保持するにはいくらですか？
これまでのところ、新しい≥の採用は95％維持されています。ポリシーの締め切りを修正します。

合計

APIの互換性は、additiveアプローチ、フォーマルなスキームとdiphs、カナリアリリース、明確な減少、マネージドマイグレーションなどの分野です。変更ポリシーを統合し、チェックと通信を自動化し、採用を測定します。更新はクライアントの破綻を防ぎ、信頼性を損なうことなく進化のスピードが向上します。