クライアントを失うことなくAPI契約を進化させる

このガイドが達成するのに役立つこと

• 契約書を作成する
• エラーを明確にする
• 互換性をテストする
• 廃止計画を策定する

クイックチェック

• 各操作はどのクライアントが使用しているか？
• エラーは安定した型と一貫性のあるステータスを持つか？
• 既存のクライアントは変更に対応できるか？
• 再試行によってアクションが重複する可能性はあるか？
• 廃止はどのように告知され、検証されるか？

手順

1. 1

   利用者を一覧化する

   操作、クライアント、使用状況、バージョン、所有者を一覧化する。 フィールドを変更する前に、実際の使用状況と想定を区別する。

   成果物：契約依存関係マップ

2. 2

   リクエストとレスポンスを説明する

   スキーマ、現実的な例、成功および失敗時のレスポンスを含むOpenAPI記述を維持する。 実行中のサービスと照合して確認する。

   成果物：バージョン管理された契約と適合性テスト。

3. 3

   エラーを安定化する。

   HTTPステータスをその意味に従って使用し、必要に応じてRFC 9457で文書化された問題タイプを使用する。機密情報を詳細に公開しない。

   成果物：テスト済みのエラーカタログ。

4. 4

   変更を分類する。

   必須フィールド、型、値、動作、タイムアウト、ページネーションを検査する。 代表的なケースを用いて、旧クライアントと新バージョンとのテストを実施する。

   成果物：互換性マトリックスとバージョン決定。

5. 5

   通知を堅牢にする。

   Webhookについては、認証、順不同配信、重複、再試行を計画する。 繰り返し処理が可能な場合は、処理を冪等にする。

   成果物：リプレイと確認応答のシナリオ。

6. 6

   終了パス付きリリース

   移行に関する注意事項、共存期間、連絡先を公開する。 旧バージョンの利用状況を測定し、影響を受けるユーザーを確認した後にのみ廃止する。

   成果物：移行計画および廃止の証拠。

管理指標

よくある間違い

• バージョン番号のみで互換性が維持されると想定している
• 200件のレスポンスのみを文書化している
• エラー時に内部トレースまたはシークレットを返す
• Webhookが一度だけ順番に到着すると想定している