保守 レッスン5
後方互換性
APIやデータ形式を変更する際に既存の利用者を壊さないための後方互換性の維持方法を学ぶ
後方互換性とは、なぜ重要か
後方互換性とは、新しいバージョンのAPIやシステムが、 古いバージョンを前提に作られたクライアントやデータからも問題なく利用できる性質のことです。 社内の他チームや外部の利用者が自分たちのAPIに依存している場合、 全員が同時に新バージョンへ移行するとは限りません。後方互換性を壊すと、 利用者側のアプリケーションが突然動かなくなるという重大な影響を及ぼします。
APIバージョニング戦略
将来の変更に備え、APIには何らかの形でバージョンを持たせておくのが一般的です。
URLパスによるバージョニング
GET /api/v1/orders/1024
GET /api/v2/orders/1024最も分かりやすく、どのバージョンを呼んでいるかログからも一目瞭然
ヘッダーによるバージョニング
GET /api/orders/1024
Accept: application/vnd.example.v2+jsonURLをきれいに保てるが、ログや動作確認がやや複雑になる
破壊的変更を避けるための指針
バージョン番号を上げなくても対応できる、安全な変更と危険な変更を見分けることが重要です。
比較的安全な変更
- レスポンスに新しい任意のフィールドを追加する
- 新しいオプションパラメータを追加する(未指定時は既存動作を維持)
- 新しいエンドポイントを追加する
破壊的になりやすい変更
- 既存フィールドの削除や型変更
- 必須パラメータの追加
- エンドポイントのパスやレスポンス構造の変更
- エラー時のステータスコードの意味を変える
非推奨化(Deprecation)のプロセス
古いバージョンやフィールドを廃止したい場合も、いきなり削除するのではなく、 猶予期間を設けた段階的なプロセスを踏みます。
1. 非推奨の告知
レスポンスヘッダーやドキュメントで "Deprecated" であることを明示する
例: Deprecation: true
Sunset: Sat, 01 Aug 2026 00:00:00 GMT
2. 移行ガイドの提供
新しいエンドポイント・フィールドへの移行手順を具体的に示す
3. 利用状況のモニタリング
非推奨エンドポイントへのアクセスが十分減るまで監視する
4. 廃止(Sunset)
告知した廃止日を過ぎてから、実際にエンドポイントを削除する猶予期間の目安
利用者が社内だけか外部にも公開しているAPIかによって、必要な猶予期間は大きく異なります。 外部公開APIほど、告知から廃止までの期間を長く取り、複数回にわたって周知することが重要です。
ポイント
- 後方互換性を壊すと、利用者側のアプリケーションに直接的な影響を及ぼす
- URLパスやヘッダーなど、何らかの形でAPIにバージョンを持たせておく
- フィールド追加は比較的安全、削除・型変更・必須化は破壊的になりやすい
- 廃止する際は告知→移行ガイド→モニタリング→廃止という段階を踏み、猶予期間を設ける
確認クイズ
1 / 3APIの変更のうち、後方互換性の観点で比較的安全とされるものはどれか？