API設計スキル

概要

RESTful APIの設計を支援するスキル。エンドポイント設計、スキーマ定義、エラーハンドリング、

ドキュメント生成までを一貫して行う。

発動条件

「API設計」「エンドポイント」「REST」「スキーマ定義」「APIドキュメント」に関する依頼を受けたとき。

入力で確認すべき情報

1. **対象リソース** — 何のデータを扱うか

2. **利用者** — フロントエンド / モバイルアプリ / 外部パートナー

3. **認証方式** — JWT / API Key / OAuth 2.0

4. **技術スタック** — Express / Hono / FastAPI / Go 等

エンドポイント命名規則

基本ルール

リソース名は**複数形の名詞**: `/users`, `/orders`, `/articles`

動詞は使わない: `/getUsers` は NG → `GET /users` が正しい

ネストは2階層まで: `/users/{id}/orders` は OK、3階層以上は避ける

ケバブケース: `/user-profiles`（キャメルケース不可）

CRUD マッピング

| 操作 | メソッド | エンドポイント | 説明 |

|------|---------|---------------|------|

| 詳細取得 | GET | `/resources/{id}` | 単一リソース |

| 更新（全体） | PUT | `/resources/{id}` | 全フィールド必須 |

| 更新（部分） | PATCH | `/resources/{id}` | 変更フィールドのみ |

| 削除 | DELETE | `/resources/{id}` | 論理削除推奨 |

非CRUD操作

アクション系: `POST /orders/{id}/cancel`

検索: `GET /search?q=keyword&type=article`

バッチ操作: `POST /resources/batch` + ボディに操作リスト

レスポンス設計

成功レスポンス

```json

{

"data": { ... },

"meta": {

"requestId": "req_abc123"

}

```

一覧レスポンス（ページネーション）

```json

{

"data": [ ... ],

"pagination": {

"page": 1,

"perPage": 20,

"total": 156,

"totalPages": 8

}

```

エラーレスポンス

```json

{

"error": {

"code": "VALIDATION_ERROR",

"message": "入力値が不正です",

"details": [

{ "field": "email", "message": "メールアドレスの形式が不正です" }

]

}

```

HTTPステータスコード

| コード | 用途 |

|--------|------|

| 200 | 成功（GET / PATCH） |

| 201 | 作成成功（POST） |

| 204 | 成功・レスポンスボディなし（DELETE） |

| 400 | バリデーションエラー |

| 401 | 未認証 |

| 403 | 権限不足 |

| 404 | リソース未存在 |

| 409 | 競合（重複登録等） |

| 422 | 処理不能（ビジネスロジックエラー） |

| 429 | レート制限超過 |

| 500 | サーバー内部エラー |

ページネーション設計

**オフセットベース**: `?page=2&perPage=20` — シンプル、総数が必要な場合

**カーソルベース**: `?cursor=abc123&limit=20` — 大量データ、リアルタイム更新がある場合

デフォルト `perPage` は 20、上限は 100

フィルタリング・ソート

フィルタ: `?status=active&created_after=2026-01-01`

ソート: `?sort=created_at&order=desc`

複数ソート: `?sort=priority,-created_at`（`-` で降順）

バージョニング

URLパス方式を推奨: `/v1/users`, `/v2/users`

ヘッダー方式（代替）: `Accept: application/vnd.api.v2+json`

破壊的変更時のみバージョンを上げる

セキュリティ

レート制限: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` ヘッダー

入力バリデーション: 全フィールドで型・長さ・形式をチェック

CORS: 許可オリジンを明示的に指定

機密データはレスポンスから除外（パスワードハッシュ等）

出力フォーマット

1. **リソース一覧**（各リソースの説明と関連）

2. **エンドポイント表**（メソッド / パス / 説明 / 認証要否）

3. **スキーマ定義**（リクエスト / レスポンスの型定義）

4. **エラーコード表**

5. **OpenAPI YAML**（要求があれば生成）