# API モジュール標準 このファイルは /src/api/ 配下のすべてに対し、ルートの CLAUDE.md を上書きする。 ## API 固有の標準 ### リクエスト検証 - スキーマ検証には Zod を使う - 入力は必ず検証する - 検証エラー時は 400 を返す - フィールド単位のエラー詳細を含める ### 認証 - すべてのエンドポイントで JWT トークンを必須とする - トークンは Authorization ヘッダに付ける - トークンの有効期限は 24 時間 - リフレッシュトークン機構を実装する ### レスポンス形式 すべてのレスポンスは次の構造に従う: ```json { "success": true, "data": { /* actual data */ }, "timestamp": "2025-11-06T10:30:00Z", "version": "1.0" } ``` エラーレスポンス: ```json { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "User message", "details": { /* field errors */ } }, "timestamp": "2025-11-06T10:30:00Z" } ``` ### ページネーション - カーソルベースページネーションを使う（オフセット方式は使わない） - `hasMore` の真偽値を含める - 1 ページの最大サイズは 100 まで - デフォルトのページサイズ: 20 ### レート制限 - 認証済みユーザー: 1 時間あたり 1000 リクエスト - 公開エンドポイント: 1 時間あたり 100 リクエスト - 上限超過時は 429 を返す - retry-after ヘッダを付ける ### キャッシュ - セッションキャッシュには Redis を使う - キャッシュ期間: デフォルト 5 分 - 書き込み操作時に無効化する - キャッシュキーにリソース種別のタグを付ける --- **Last Updated**: April 9, 2026