Instruction file imported from yusay1498/dao-sample-2026-1d (
.github/instructions/api-design.instructions.md). Copyright stays with the author.
REST API設計 レビュー観点
リソース設計（URI）
- URIにはリソース名（名詞・複数形）を設定し、システム自明語（
App等）や抽出条件を表す語（all/search）を含めていないか /dailySalesSummaries/allのような抽出条件をリソース名に含める設計を避け、GET /リソース名で全件・検索を表現しているか- サブリソースは階層構造で表現し、他リソースとの整合を取っているか（例:
/kintai/{employeeId}/today） - 複数の異なるエンティティを同一URIで扱っていないか
- PathVariableはエンティティIDのみに使用し、検索条件はRequestParamで表現しているか
- RequestParamの引数には明示的に名前を付けているか（ビルド時に引数名情報が失われる場合の対策）
HTTPステータス・レスポンス設計
- リソース作成時（POST）は
201 Created+Locationヘッダ、更新時は200 OKを返しているか - 二重登録エラーには
409 Conflictを活用しているか - 「正しい条件で検索した0件」は404でなく空のリスト（
Page.empty()）で表現し、「不正な条件・存在しないリソース」との違いを区別しているか（1件リソース取得の場合は404が自然） - ページネーションはSpring標準の
Pageable/Pageを利用し、独自のmetaフィールドを作っていないか - 戻り値の型に
ResponseEntityを使い、Locationヘッダ等を柔軟に扱えるようにしているか
エラーレスポンス
- エラーレスポンスはRFC 9457 Problem Detailsに準拠しているか
detailフィールドに具体的な不正内容を記載し、フロントのリトライ・表示に活用できる情報を含めているか- クライアントへのレスポンスにクラス名やスタックトレース等の内部実装情報を含めていないか
CORS
- CORSの許可メソッドは、現在cross-originクライアントが使用するものだけに限定しているか
- PreflightリクエストはCORS filterまたはsecurity chainで正しく処理され、要求された実メソッドに必要な
Access-Control-Allow-Methodsを返しているか