specsfy-specialist-web-api-design

Web API 設計

使用するタイミング

• 社内外の利用者向けに、HTTP、REST、JSON、webhook、OpenAPI の記述を設計またはレビューするときに使用します。
• リソース、メソッド、ステータス、エラー、ページネーション、冪等性、並行性、認証、互換性に関する判断に使用します。
• 実際の契約スタイルを最初に確認せず、RPC やイベントを HTTP リソースとして扱う場合には使用しません。
• 脅威モデリング、認証情報、悪用、信頼境界については、$specsfy-specialist-application-security と組み合わせます。

ワークフロー

1. 利用者、ユースケース、既存のスタイル、ボリューム、レイテンシ、可用性、信頼境界、互換性ポリシーを確認します。
2. テーブルや内部オブジェクトを便宜上そのまま契約として公開することなく、リソース、識別子、関係、不変条件、所有権をモデル化します。
3. 操作、スキーマ、ヘッダー、ステータス、Problem Details を定義し、各操作のリトライの意味を references/standards.md に従って記録します。
4. ハンドラーを実装する前に、認証、リソース／テナント単位の認可、冪等性、事前条件、並行性を設計します。
5. ページネーション、フィルター、決定的な並べ替え、制限、レート制限、データ変更時の動作を定義します。
6. OpenAPI／JSON Schema を作成し、実装に対して実行する正常系、異常系、互換性のコントラクトテストを用意します。
7. 既知の利用者を壊すことなく古い動作を削除するためのログ、メトリクス、相関、非推奨化、移行、基準を定義します。

パターン

• 一貫した HTTP セマンティクスと具体的なステータスを使用します。
• 安定していて、対処可能で、情報を漏らさないエラー形式を維持します。
• 長時間のページネーション中にデータが変化する場合は、カーソルを使用します。
• 必要に応じて冪等性キーを使い、作成やリトライを安全にします。
• webhook を署名、タイムスタンプ、リプレイ防止、再配信で保護します。
• 予告なしの破壊的変更や、意味が曖昧なフィールドを避けます。
• 便宜上、永続化モデルをそのまま契約として公開しないでください。

アンチパターン

• すべての結果に 200 を返し、失敗を body だけで表現します。キャッシュ、クライアント、可観測性でプロトコルの意味が失われます。
• 冪等性や照合処理なしに、タイムアウト後に POST を再試行します。応答が失われると、請求、注文、外部への影響が重複する可能性があります。
• 安定した並べ替えのない大規模で変更可能なコレクションに対し、offset でページネーションします。ページ間で項目が重複したり、欠落したりします。
• エンドポイント／リストでのみ認可し、読み込んだリソースでは認可しません。有効な ID によってテナントやスコープを越えられる可能性があります。
• 追加的な変更のたびに URL のバージョンを上げます。互換性の管理を改善せずに、アクティブな契約が増えていきます。

検証

• 記述の有効な例と無効な例を使って、request、response、ヘッダー、Problem Details のコントラクトテストを実装に対して実行します。
• 正しい ID、別の ID、期限切れの認証情報、不十分なスコープを使って、リソース単位およびテナント単位の認可を検証します。
• リトライ、重複、コミット後のタイムアウト、更新の競合、項目が追加・削除される間のページネーションをシミュレーションします。
• OpenAPI／JSON Schema の lint と構造検証を行い、公開済みの最新バージョンと破壊的変更を比較します。
• 利用者から観測される契約に対するリプレイと自動テストの証拠なしに、互換性や冪等性を宣言しないでください。

関連するスキル

• $specsfy-specialist-astro はフレームワーク内のエンドポイントを実装します。このスキルは、 サイト外から利用できる HTTP 契約を維持します。
• $specsfy-specialist-application-security は脅威モデリング、OAuth、 シークレットの保護、不正利用、信頼境界を扱います。
• $specsfy-specialist-domain-modeling は、語彙と不変条件を定義してから リソースとして公開します。
• $specsfy-specialist-typescript は、内部の型をモデル化しますが、それらを 自動的に契約の公開ソースにすることはありません。
• $specsfy-specialist-observability は、契約の相関フィールドに加えて、 テレメトリーと SLO を定義します。
• $specsfy-specialist-performance-engineering は、ベンチマークの数値を上げるために セマンティクスを変更することなく、スループットとレイテンシーを測定します。

メソッド、エラー、冪等性、並行性、ページネーション、Webhook、後方互換性のある進化に関する マトリックスについては、references/standards.md をお読みください。