api-design-and-evolution

API の設計と進化

インターフェースは、ルートの一覧ではなく、利用者との長期的な合意として設計します。 まず利用者の目的、ドメイン上の意味、権限の境界、障害モードを明確にし、 そのうえでインターフェースのスタイルと契約形式を選びます。事実、前提、ポリシー上の決定は 区別できるようにしてください。

使用する場合

新規または変更する REST/HTTP API、GraphQL スキーマ、RPC オペレーション、イベントまたは メッセージの契約、Webhook、ストリーミングインターフェースに使用します。実装前に使用し、 利用者から見える動作が変わるたびに再度使用してください。

使用しない場合

ADR のテンプレート、完全なプロダクト発見の手法、セキュリティ評価、実装のテスト計画として 使用しないでください。それぞれの懸念事項は、 adr-authoring、 product-discovery、 secure-software-engineering、および verification-methodologyに委ねてください。

ワークフロー

1. 対象範囲を分類します。 複数のインターフェースにまたがるリクエストの場合は、 templates/api-landscape-assessment.md を開始し、 references/api-landscape-and-governance.md を読みます。 トラフィックの受付、ルーティング、観測、分離の方法を変更する場合は、 references/api-infrastructure-topologies.md を読みます。 ポートフォリオ全体の調査結果と、個別の契約に関する判断は分けて扱います。
2. 合意事項を明らかにします。 コンシューマーの業務、ドメイン用語と不変条件、 正式なデータおよびスキーマのオーナー、アクター、オブジェクト／アクションの権限境界、 データの機密性、障害モードを明記します。方針を憶測で作らず、未回答の質問を記録します。 templates/api-design-brief.md を開始します。 エージェントまたは自動化が直接のコンシューマーとなる場合は、 references/agent-consumer-interfaces.md も読み、 templates/agent-consumer-interface-review.md を完成させます。
3. インターフェースの形状を選びます。 インタラクションの方向、結合度、 配信要件、クエリの柔軟性、変更の意味論、キャッシュ、可観測性、 進化の範囲を比較します。references/interface-selection.md を読みます。 選択した案と採用しなかった案をブリーフに記録します。ADR を使うのは、 その選択がこのインターフェースを超えて重大な影響を及ぼす場合に限ります。
4. 契約を明確に定義します。 表現形式とその意味論を定義します。 null と未指定の違い、デフォルト値、列挙型／ユニオン、識別子、タイムスタンプ、 単位、順序、フィルタリング、ページネーションを含めます。 templates/endpoint-contract.md を references/contract-semantics.md と併せて使用します。
5. 変更操作と障害時の動作を設計します。 権限チェック、事前条件、 冪等性の適用範囲と同等性、再試行、並行性、部分的な結果、 長時間実行される操作の状態、エラー、リソース制限を定義します。 references/operations-and-failures.md を読み、 複数の操作でエラーを共有する場合は templates/error-taxonomy.md を作成します。
6. 該当する場合は非同期配信を説明します。 メッセージ、ウェブフック、ストリームについて、 パブリッシャー／サブスクライバーの視点、エンベロープ、配信契約、 重複／欠落／順序変更への対応、順序の適用範囲、セキュリティ境界を明記します。 references/events-webhooks-streaming.md を読みます。
7. 各コンシューマーの視点から変更を評価します。 コンシューマー、 生成クライアント、厳密なデコーダー、署名、キャッシュ、クォータ、運用上の依存関係を洗い出します。 templates/compatibility-change-assessment.md を完成させます。 追加的な変更であるという理由だけで、安全な変更と判断してはいけません。
8. ロールアウトを計画し、検証します。 非推奨化または移行の場合は、 templates/deprecation-migration-plan.md と references/evolution-and-deprecation.md を使用します。 templates/contract-review.md を使用して契約をレビューします。 プロバイダーの準拠性、コンシューマーの期待、互換性の差分、例、 異常系、デプロイされた境界をテストします。 互換性ポリシーを定義した後、 release-engineering を読み込み、リリースの順序、 成果物の昇格、段階的な公開、協調的なロールバックを確認します。

リファレンスガイド

読み込むタイミング	ファイル
API ポートフォリオ、所有権、重複、発見可能性、ライフサイクル、標準、または廃止を評価するとき	references/api-landscape-and-governance.md および templates/api-landscape-assessment.md
ゲートウェイ、イングレスプロキシ、サービスメッシュ、トラフィックの方向、ルーティング、ポリシー、テレメトリー、または障害境界を比較するとき	references/api-infrastructure-topologies.md
REST/HTTP、GraphQL、RPC、イベント／メッセージ、Webhook、またはストリーミングを選択するとき	references/interface-selection.md
データ、コレクションの読み取り、スキーマ、または OpenAPI をモデリングするとき	references/contract-semantics.md
書き込み、エラー、再試行動作、制限、または認可の引き継ぎを設計するとき	references/operations-and-failures.md
イベントコントラクト、Webhook 配信、またはストリームを設計するとき	references/events-webhooks-streaming.md
互換性、バージョン、非推奨化、移行、またはロールバックをレビューするとき	references/evolution-and-deprecation.md
コントラクト、プロバイダー、コンシューマー、デプロイの検証を準備するとき	references/contract-verification.md
正確な情報源、バージョン、ステータス、想定される用途を確認するとき	references/source-index.md
エージェントや自動化が直接利用する API またはツールをレビューするとき	references/agent-consumer-interfaces.md および templates/agent-consumer-interface-review.md
準備完了と判断する前に、必須のエッジケースを検証するとき	references/scenario-probes.md

セキュリティ境界

認証要件とサーバー側のオブジェクト／アクション認可をインターフェースコントラクトに記載してください。脅威モデル、認証情報の取り扱い、テナント分離、信頼できない URL やファイル、Webhook 署名の設計、出力の最小化、編集による機密情報の除去、または不正利用への耐性については、 secure-software-engineering を読み込んでください。API コントラクトだけでは、認可境界が適切に適用されていることを証明できません。

所有権の境界

• プロダクトオーナーは、コンシューマーにとっての成果、対象者、価値、ライフサイクルの方針を決定します。このスキルは、それらの決定をインターフェース合意とエビデンスに反映します。
• プラットフォームオーナーは、ゲートウェイ、イングレス、メッシュ、ネットワーク、デプロイ、ランタイム運用を決定します。このスキルは、トポロジー上の責任とコントラクトへの影響を特定しますが、基盤の運用は行いません。
• セキュリティオーナーは、脅威モデル、認証情報とシークレットの管理、不正利用への耐性、テナント分離を決定します。このスキルは、評価に代わることなく、コントラクトの引き継ぎと必要な認可動作を記録します。
• アーキテクチャオーナーは、システム横断の原則、重要な境界、永続的なアーキテクチャ上の決定を行います。ランドスケープやトポロジーに関する決定が API ポートフォリオを超える影響を及ぼす場合は、adr-authoring を使用してください。

API ランドスケープの評価は、プロダクトロードマップ、プラットフォーム運用手順書、セキュリティレビュー、またはエンタープライズアーキテクチャのリポジトリではありません。所有権、権限、または廃止に関する未解決の判断は、暗黙のうちに割り当てず、エスカレーションしてください。

完了

選択したインターフェースにオーナーが割り当てられ、正式なコントラクトが定まり、コンシューマーと障害に関する前提が明示され、変更ごとに互換性が評価され、必須のレビュー項目ごとにエビデンスまたは明示的な不足がある状態になったら、終了してください。ドメインの意味、権限、配信、またはコンシューマーへの影響に関する未解決の問題は、責任を持つオーナーにエスカレーションしてください。