API設計レビュー は何をしますか？
概要
APIをクライアントの視点から評価します。予測可能な名前、誠実なステータスコード、統一されたエラー形状、安全なリトライ、そして予期しない破壊的変更がないこと。各発見は具体的なルートを指し示し、修正された設計を示します。
方法
- インベントリ. すべてのエンドポイントを
METHOD /path → ステータスコード → リクエスト/レスポンス形状としてリストアップします。ルート、コントローラ、OpenAPIファイル、DTOを読みます。 - 各エンドポイントのチェック 下記ルールに従って行います。
- API全体のチェック: エンドポイント間の一貫性は、個々の選択よりも重要です。
- 変更: diffをレビューする場合、新旧コントラクトを比較し、既存クライアントを破壊するものをフラグ付けします。
- レポート 下記の出力契約に従って作成します。
ルール
| 領域 | ルール |
|---|---|
| リソース | 複数形の名詞、動詞は使いません: POST /orders、/createOrder ではありません。真の所有関係のみ入れ子に: /users/{id}/orders。 |
| メソッド | GETは読み取りで安全。POSTは作成。PUTは置換。PATCHは部分更新。DELETEは削除。GETで状態を変更してはいけません。 |
| ステータスコード | 200 OK、201 Created (+ Location)、204 No Content、400 不正な入力、401 未認証、403 許可なし、404 存在しない、409 競合、422 バリデーション、429 レート制限、5xxはサーバー障害のみ。200で {"error": ...} を返してはいけません。 |
| エラー | 全箇所で統一された形状、例: RFC 9457: { "type", "title", "status", "detail", "errors": [{ "field", "message" }] }。レスポンスにスタックトレースやSQLを含めてはいけません。 |
| 命名 | JSONフィールドのケーシングを統一（camelCase または snake_case）、一貫したID、ISO 8601 UTCタイムスタンプ、金額は整数の最小単位または10進数の文字列＋通貨。 |
| コレクション | すべてのリストにページネーション（大規模または変化するデータにはカーソル推奨）、ページサイズ上限設定、次のカーソルまたはリンクを返す。フィルタリングとソートはクエリパラメータ経由。 |
| 冪等性 | 支払い、注文、メールを作成するPOSTのリトライは Idempotency-Key を受け付けます。PUTとDELETEは設計上冪等です。 |
| バージョニング | 明確な戦略（/v1 パスまたはヘッダー）。破壊的変更は新しいバージョンへ。 |
| 破壊的変更 | フィールドの削除や名前変更、型の変更、オプション入力の必須化、ステータスコードやエラー形状の変更、バリデーションの厳格化。 |
| セキュリティ | 公開されていないすべてのルートに認証、オブジェクトレベルの所有権チェック、認証と高負荷ルートにレート制限、URLに機密データを含めない。 |
| パフォーマンス | 無制限のレスポンスなし、大きなオブジェクトには fields またはスパースレスポンスをサポート、キャッシュ可能なGETにはETagまたはCache-Control。 |
出力契約
以下で開始: N エンドポイントレビュー済み、M 発見（うちX 破壊的変更）。 その後、影響度の高い順に:
### [Breaking | High | Medium | Low] タイトル
- エンドポイント: METHOD /path (ファイル:行)
- 問題: クライアントが体験すること
- 修正: 修正されたルート、ステータスコード、またはJSON形状
最後に短い 一貫性サマリー（ケーシング、エラー形状、ページネーション、バージョニング: 一貫しているかどうか）と、ゼロから設計する場合は提案エンドポイント表を記載します。
よくある間違い
- エンドポイントを一つずつレビューし、2つのエンドポイント間でケーシングやエラー形状が一致していないことを見逃す。
- 後方互換性のある追加で十分なのに、再設計を推奨する。
- サーバーコードがまだ動作するから変更は安全だと判断する: 既存クライアントが送信・期待しているものを確認すること。
- バリデーションエラーに500を使用したり、許可エラーに404を使用したりする際に意図的な決定を省略する。