API は『1度公開したら簡単に変えられない』前提で設計
外部に公開した API は契約です。本記事では編集部の視点で、後方互換性を保ちつつ進化させるバージョニング戦略を公開情報をもとに整理します。REST API設計 もご参考に。
バージョニング方式
(1) URL パス：/v1/users(分かりやすく一般的)。(2) ヘッダー：Accept: application/vnd.example.v2+json。(3) クエリパラメータ：?version=2。(4) ホスト名分離：api-v2.example.com。(5) 採用率：URLパスが最も普及。
後方互換性の維持
(1) フィールド追加は OK：必須は避ける。(2) フィールド削除は破壊：避けるか deprecation で警告。(3) 意味の変更は禁止：型・単位・形式。(4) エラーレスポンスの追加はOK。(5) 必須パラメータの増加は破壊。JSON は『追加に強く削除に弱い』ことを前提に。
破壊変更が必要な時
(1) 新バージョンの作成：/v2 を併存させる。(2) 並行運用期間：最低6ヶ月〜1年。(3) 明確な deprecation 期日：日付を公表。(4) 移行ガイド：差分表とコード例。(5) 移行リマインダー：レスポンスヘッダ・メール通知。
廃止プロセスの設計
(1) Deprecation ヘッダ：HTTP 仕様(RFC 8594)。(2) Sunset ヘッダ：廃止予定日。(3) 利用量モニタリング：誰が使っているか把握。(4) 個別通知：主要利用者には直接連絡。(5) 段階的ストップ：429 → 410 で誘導。Observability 実践 でAPI 利用量も計測。
外向きと内向きの違い
(1) 外向きAPI：契約として厳格に。(2) 内向きAPI：チーム調整で柔軟に。(3) SDK 提供：内部実装の変更を隠蔽。(4) GraphQL の deprecation：フィールド単位で。(5) gRPC のスキーマ進化：proto の互換性ルール。gRPC 実践 もご参考に。
失敗しがちなパターン
(1) 後方互換を破る変更を黙って出す：障害発生。(2) バージョン乱立：v1〜v5 が並存し保守困難。(3) 廃止期日が不明確：移行が進まない。(4) 利用量を把握していない：影響範囲不明。(5) 移行ガイドが不足：開発者からの問い合わせ集中。対策は、(1)契約テスト、(2)廃止ロードマップ公開、(3)明確な期日、(4)アクセスログ分析、(5)サンプルコード+FAQ、です。