design-api

API 設計スキル

自由度：混合。 リソースモデル、エラー形式、REST と GraphQL は「自由度高」。設計前のドキュメント／スキーマ／grep は 「自由度低 — 必ずそのまま実行」。

クリーンで一貫性があり、開発者にとって使いやすい API を設計します。

考え方

1. 調査 — 既存のドキュメント、スキーマ、類似エンドポイントを確認します
2. モデル化 — リソース、関連、REST と GraphQL を検討します
3. 契約 — パス、ステータス、エラー形式、認証、ページネーションを定めます
4. 確認 — 命名がこのリポジトリに合っていること、重複するエンドポイントがないことを確認します

作業例

調査： orders には user_id がありますが、GET /users/:id/orders はありません。クライアントは useQuery を使用しています。 モデル化： 注文は /getUserOrders のような RPC ではなく、ユーザーにネストされたリソースです。 契約： GET /users/:id/orders → { data, meta }。共通の { error: { code, message, details } } を使用します。 確認： 複数形のケバブケース。リストはページネーション対応。ステータステーブルから返すのは 401／404／422 のみです。

報告前の自己批評

• 設計前の確認を明示 — ドキュメント、スキーマ、類似エンドポイントを確認したことを、はっきり述べました
• エラー形式は一つ — すべてのエラーで { error: { code, message, details } } を使用します
• リストはページネーション対応 — 上限のない GET /resources はありません
• 適切な担当先 — 実環境での 4xx／5xx の再現 → debug-fe-be-integration。プロダクトのスコープがまだ曖昧 → design-prd

設計前の確認 [自由度低 — 必ずそのまま実行]

API を設計する前に：

1. 既存の API ドキュメントを確認する

• 稼働中のバックエンドのドキュメントルート（/api-docs、/docs、/swagger、/openapi.json）
• リポジトリの API README または命名規則のドキュメント（docs/ と src/api/ で naming を grep）

2. データベーススキーマを確認する

Supabase MCP を使用して、既存のデータ構造を確認します：

SELECT column_name, data_type, is_nullable
FROM information_schema.columns WHERE table_name = 'your_table';

列挙型の値（enum_range）と外部キー（information_schema.table_constraints）も確認します： references/examples.md §設計前のスキーマ調査。

3. 既存のエンドポイントを確認する

Grep を使用して、すでに実装されている類似エンドポイントを検索します：

Grep: "router.get|router.post" to find existing route patterns
Grep: "useQuery|useMutation" to find existing frontend integrations

4. 確認内容の明示（必須）

設計を始める前に、次のように述べます：

"Pre-design check:
- Existing API docs reviewed: [YES/NO]
- Database schema verified: [tables/enums checked]
- Similar endpoints found: [list or none]
- Naming conventions confirmed: [YES/NO]"

---

REST API 設計 [自由度高]

URL 構造

GET /resources # List
GET /resources/:id # Get one
POST /resources # Create
PUT /resources/:id # Replace
PATCH /resources/:id # Update
DELETE /resources/:id # Delete

命名規則

使用する	使用しない
/users	/getUsers、/user-list
/users/:id	/user/:id、/users/get/:id
/users/:id/orders	/getUserOrders
複数形の名詞	動詞、単数形
ケバブケース	キャメルケース、スネークケース

例

GET /users # List users
GET /users/123 # Get user 123
GET /users/123/orders # User's orders
GET /users/123/orders/456 # Specific order
POST /users/123/orders # Create order for user

---

リクエスト／レスポンス形式 [自由度低 — この形式を使用]

• リクエストボディ — フラットな JSON。キーはキャメルケースで、エンベロープは使用しません。
• 成功 — 単一リソースには { "data": { ... } }、リストには { "data": [...], "meta": { total, page, perPage, totalPages } } を使用します。
• エラー — すべてで共通の形式 { "error": { "code", "message", "details" } } を使用します。code は機械可読で、details はフィールドごとのリストです。

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

リクエスト、単一リソース、リストの完全なボディについては、references/examples.md §リクエストボディから§リストレスポンスまでを参照してください。

---

HTTP ステータスコード [自由度低 — この表を使用]

成功（2xx）

コード	使用する場面
200 OK	GET、PUT、PATCH の成功
201 Created	POST で新しいリソースを作成した場合
204 No Content	DELETE の成功。ボディなし

クライアントエラー（4xx）

コード	使用する場面
400 Bad Request	リクエストボディが無効
401 Unauthorized	認証されていない
403 Forbidden	認証済みだが許可されていない
404 Not Found	リソースが存在しない
409 Conflict	リソースの競合（重複）
422 Unprocessable	バリデーションに失敗
429 Too Many	レート制限に達した

サーバーエラー（5xx）

コード	使用する場面
500 Internal Error	予期しないサーバーエラー
502 Bad Gateway	上流サービスのエラー
503 Unavailable	サービスが一時的に停止

---

クエリパラメーター

• フィルタリング — ?role=admin&status=active、日付範囲は ?createdAfter=2024-01-01 を使用します。
• 並べ替え — ?sort=name を使用します。降順には - 接頭辞を付けます。複数指定する場合はカンマで区切ります（?sort=role,-name）。
• ページネーション — デフォルトでは ?page=2&perPage=20 を使用します。大規模なリストや更新され続けるリストには ?cursor=abc123 を使用します。上限のないリストは使用しないでください。
• フィールド選択 — ?fields=id,name,email を使用します。関連データは ?include=orders,profile で指定します。

各項目の URL 例：references/examples.md §クエリパラメーター。

---

バージョニング

デフォルト：URL パス（GET /v1/users、GET /v2/users）を使用します。代替手段として、ヘッダーでのバージョニング（Accept: application/vnd.api+json;version=2）があります： references/examples.md §バージョニング。

---

認証

デフォルト：Authorization: Bearer <token> を使用します。サーバー間の呼び出し元には、代替手段として X-API-Key ヘッダー（または ?apiKey=）による API キー認証があります：references/examples.md §認証。

---

一般的なパターン

• 一括操作 — { create: [...], update: [...], delete: [ids] } を指定して POST /users/bulk を使用します。
• 検索 — 条件がクエリ文字列に収まらない場合は、{ query, filters, sort } を指定して POST /users/search を使用します。
• アクション（CRUD 以外） — 名詞の下に動詞のサブリソースを配置します：POST /orders/123/cancel、POST /users/123/verify-email、POST /payments/123/refund。

一括操作と検索のリクエストボディ：references/examples.md §一括操作、§検索。

---

API 設計チェックリスト [LOW freedom — do not skip]

一貫性

• 命名規則に一貫性がある
• レスポンス形式に一貫性がある
• エラー形式に一貫性がある
• ページネーションに一貫性がある

使いやすさ

• URL が直感的である
• ドキュメントが明確である
• エラーメッセージに意味がある
• 適切なデフォルト値が設定されている

セキュリティ

• 認証が必須である
• 認可が確認される
• 入力が検証される
• レート制限がある

パフォーマンス

• リストにページネーションがある
• フィールド選択が利用できる
• クエリが効率的である
• キャッシュヘッダーがある

---

ドキュメントのテンプレート

エンドポイントごとに、タイトル、目的を示す 1 行の説明、**Endpoint:**、**Authentication:**、リクエストボディの表（フィールド、型、必須かどうか、説明）、JSON の例を含むレスポンスステータス、エラーの一覧を記載します。テンプレート全体：references/examples.md §ドキュメントのテンプレート。