api-design

API 設計

概要

ガイド付きの探索を通じて、構造化された API エンドポイントを設計します。OpenAPI／Swagger 仕様に基づく、一貫性のある十分に文書化された API 設計を作成します。リソースのモデリング、認証、ページネーション、エラー処理、バージョニングを網羅し、実装を始める前にコンシューマー中心の設計を確立します。

開始時に伝えること： 「API の設計に api-design スキルを使用します。」

フェーズ 1：探索

次の質問を1つずつ尋ねます。

リソースに関する質問

#	質問	判断する内容
1	この API が管理するエンティティ／リソースは何ですか？	リソースの命名
2	それらの間にはどのような関係がありますか？	ネストされたルート、インクルード
3	それぞれにどのような操作が必要ですか？（CRUD、検索、一括処理）	HTTP メソッド、エンドポイント

コンシューマーに関する質問

#	質問	判断する内容
4	この API を利用するのは誰ですか？（フロントエンド、モバイル、サードパーティ、社内）	レスポンスの形式、認証モデル
5	どのような認証／認可が必要ですか？	セキュリティスキーム
6	適用されるレート制限やクォータはありますか？	レート制限ヘッダー

制約に関する質問

#	質問	判断する内容
7	REST、GraphQL、tRPC のどれを使いますか？	API のパラダイム
8	バージョニング戦略は何ですか？（URL パス、ヘッダー、クエリパラメーター）	URL の構造
9	ページネーション方式は何ですか？（カーソル、オフセット、キーセット）	リストレスポンスの形式
10	コードベースに既存の API 規約はありますか？	一貫性に関する制約

API パラダイムの判断表

要素	REST を選択	GraphQL を選択	tRPC を選択
コンシューマー	複数で多様	フロントエンド中心で、柔軟なクエリが必要	TypeScript のモノレポ
キャッシュの必要性	高い（HTTP キャッシュ）	中程度（クライアント側）	低い（内部利用のみ）
データの形状	予測可能で、リソース指向	ネストされ、形状が可変	型安全な RPC
チームの習熟度	広く普及	スキーマの知識が必要	TypeScript が必要
リアルタイムの必要性	WebSocket アドオン	サブスクリプションを標準搭載	サブスクリプションをサポート

探索が終わったら停止し、リソース、操作、制約の概要を提示します。エンドポイントの設計に進む前に確認を得ます。

フェーズ 2：エンドポイントの設計

各エンドポイントについて、以下を定義します。

### [METHOD] /api/v1/[resource]

**Purpose:** [what this endpoint does]

**Request:**
- Headers: `Authorization: Bearer <token>`
- Query params: `?page=1&limit=20&sort=created_at:desc`
- Body:
  ```json
  {
    "field": "type — description"
  }

レスポンス（200）：

{
  "data": [...],
  "meta": { "total": 100, "page": 1, "limit": 20 }
}

エラーレスポンス：

ステータス	コード	説明
400	VALIDATION_ERROR	リクエストボディが無効です
401	UNAUTHORIZED	トークンがないか、無効です
404	NOT_FOUND	リソースが存在しません
409	CONFLICT	リソースはすでに存在します

認可：［アクセスできるユーザー］

### HTTP Method Decision Table

| Operation | Method | Status (success) | Idempotent |
|-----------|--------|-----------------|------------|
| List resources | GET | 200 | Yes |
| Get single resource | GET | 200 | Yes |
| Create resource | POST | 201 | No |
| Full replace | PUT | 200 | Yes |
| Partial update | PATCH | 200 | No |
| Delete resource | DELETE | 204 | Yes |
| Bulk create | POST | 201 | No |
| Search (complex) | POST | 200 | Yes (safe) |

### Pagination Decision Table

| Approach | When to Use | Pros | Cons |
|----------|------------|------|------|
| **Cursor** | Real-time feeds, large datasets | Consistent, no skipping | Cannot jump to page N |
| **Offset** | Small datasets, admin panels | Simple, jumpable | Skips/duplicates on insert |
| **Keyset** | Time-series, logs | Efficient on large tables | Requires sortable key |

### Error Response Format

All endpoints must use a consistent error shape:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

ステータスコードの参照表

コード	意味	使用する状況
200	OK	GET、PUT、PATCH が成功した場合
201	作成済み	リソースを作成する POST が成功した場合
204	コンテンツなし	DELETE が成功した場合
400	不正なリクエスト	検証に失敗した場合
401	認証されていない	認証情報がないか、無効な場合
403	禁止	認証情報は有効だが、権限が不十分な場合
404	見つからない	リソースが存在しない場合
409	競合	重複または状態の競合がある場合
422	処理できないエンティティ	JSON は有効だが、意味上のエラーがある場合
429	リクエストが多すぎる	レート制限を超過した場合
500	内部サーバーエラー	予期しないサーバー障害が発生した場合

エンドポイントの設計が終わったら停止し、各エンドポイントを提示してレビューと承認を得ます。

フェーズ 3：OpenAPI 仕様の生成

openapi: 3.1.0
info:
  title: [API Name]
  version: 1.0.0
  description: [API description]

servers:
  - url: http://localhost:3000/api/v1
    description: Development
  - url: https://api.example.com/v1
    description: Production

paths:
  /resource:
    get:
      summary: List resources
      parameters: [...]
      responses: [...]
    post:
      summary: Create resource
      requestBody: [...]
      responses: [...]

components:
  schemas: [...]
  securitySchemes: [...]

仕様の生成後に停止し、YAML を検証して最終承認のために提示します。

フェーズ 4：保存と次の作業への移行

明示的な承認を得た後：

1. OpenAPI 仕様を docs/api/YYYY-MM-DD-<api-name>.yaml に保存します
2. コミットメッセージを docs(api): add OpenAPI spec for <api-name> としてコミットします
3. ユーザーの意図に基づいて次のステップを決定します

遷移判断表

ユーザーの意図	次のスキル	理由
「これを実装しましょう」	planning	API 仕様から実装計画を作成します
「これの仕様を書いてください」	spec-writing	各エンドポイントの動作仕様を作成します
「クライアント SDK を生成してください」	手動	OpenAPI コード生成ツールを使用します
「設計を保存するだけです」	なし	API 設計が成果物です
「テストを追加してください」	testing-strategy	API のテスト方針を定義します

設計原則

原則	ルール
一貫した命名	コレクションには複数形の名詞を使います（/user ではなく /users）
適切な HTTP メソッド	GET は読み取り、POST は作成、PUT は置換、PATCH は更新、DELETE は削除に使います
適切なステータスコード	状況に合ったコードを使用します（上の表を参照）
一貫したエラー形式	すべてのエンドポイントで同じエラー形式を使います
デフォルトでページネーション	すべてのリストエンドポイントにページネーションを設定します
フィルタリングと並べ替え	リストエンドポイントにはクエリパラメーターを使います
冪等性	PUT と DELETE は常に冪等です
HATEOAS	発見しやすいようにリンクを含めます（適切な場合）

アンチパターン／よくある間違い

間違い	問題点	代わりに行うこと
動詞ベースの URL（/getUsers）	RESTful ではなく、慣習にも反します	名詞を使います：GET /users
単数形と複数形の不統一	利用者を混乱させます	コレクションには必ず複数形を使います
エラーに対して 200 を返す	クライアントから障害が見えなくなります	適切なステータスコードを使います
リストエンドポイントにページネーションがない	大規模なデータセットでパフォーマンスの問題が発生します	必ずページネーションを設定します
エンドポイントごとに異なるエラー形式	クライアントで汎用的なエラー処理を構築できません	すべてに共通のエラー形式を使います
URL で内部 ID を公開する	セキュリティと密結合のリスクがあります	UUID またはスラッグを使います
バージョニング戦略がない	破壊的変更によってクライアントに問題が生じます	最初からバージョンを付けます
利用者を把握せずに設計する	API が誰にとっても使いにくくなります	まず調査を行います

不適切な正当化を防ぐための注意事項

• 決して調査フェーズを省略しないでください。まず利用者と制約を把握します
• 決してエラー応答を定義せずにエンドポイントを設計しないでください
• 決してリストエンドポイントのページネーションを省略しないでください
• 決してエンドポイント間で一貫性のない命名を使わないでください
• 決してユーザーがエンドポイント設計を承認する前に OpenAPI 仕様を生成しないでください
• 決して明確な理由なく API パラダイム（REST + GraphQL）を混在させないでください

統合ポイント

スキル	関係
spec-writing	下流：API 設計が動作仕様に反映されます
planning	下流：API エンドポイントが実装タスクになります
tech-docs-generator	下流：OpenAPI 仕様が API リファレンスドキュメントに活用されます
testing-strategy	下流：API 設計が統合テスト戦略に反映されます
security-review	下流：認証／認可モデルの脆弱性をレビューします
database-schema-design	上流：データモデルがリソース設計に反映されます
prd-generation	上流：PRD の要件が API リソースの特定につながります

検証ゲート

API 設計が完了したと判断する前に：

1. すべてのエンドポイントにリクエスト／レスポンスのスキーマがあることを検証します
2. すべてのエラー応答が一貫した形式で文書化されていることを検証します
3. 各エンドポイントの認証が指定されていることを検証します
4. すべてのリストエンドポイントでページネーションが定義されていることを検証します
5. OpenAPI 仕様が有効な YAML であることを検証します
6. ユーザーが各エンドポイントを個別に承認したことを検証します

スキルの種類

柔軟 — 調査を優先するアプローチ、一貫したエラー処理、利用者中心の設計原則を保ちながら、API パラダイム、ページネーション方式、認証モデルをプロジェクトのニーズに合わせて調整します。