# API Design

> RESTful API の設計とドキュメント生成。 エンドポイント設計、リクエスト/レスポンス定義、OpenAPI仕様出力。 API設計、エンドポイント作成、APIドキュメント生成時に使用。

- Skill: `atomic-kanta-sasaki/api-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add atomic-kanta-sasaki/api-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/atomic-kanta-sasaki/api-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: atomic-kanta-sasaki (https://skillmd.com/u/atomic-kanta-sasaki)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/atomic-kanta-sasaki/api-design

---


# API Design Skill

## Overview
RESTful APIのベストプラクティスに基づいた設計を支援します。

## Design Principles

### 1. リソース命名
- 名詞を使用（動詞は避ける）
- 複数形を使用: `/users`, `/orders`
- ケバブケース: `/user-profiles`
- ネストは2階層まで: `/users/{id}/orders`

### 2. HTTPメソッド
| メソッド | 用途 | 冪等性 |
|---------|------|--------|
| GET | リソース取得 | ✅ |
| POST | リソース作成 | ❌ |
| PUT | リソース全体更新 | ✅ |
| PATCH | リソース部分更新 | ❌ |
| DELETE | リソース削除 | ✅ |

### 3. ステータスコード
| コード | 用途 |
|--------|------|
| 200 | 成功（GET, PUT, PATCH） |
| 201 | 作成成功（POST） |
| 204 | 成功・レスポンスなし（DELETE） |
| 400 | リクエスト不正 |
| 401 | 認証エラー |
| 403 | 認可エラー |
| 404 | リソース未発見 |
| 409 | 競合（重複など） |
| 422 | バリデーションエラー |
| 500 | サーバーエラー |

### 4. レスポンス形式

#### 成功レスポンス
```json
{
  "data": { ... },
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20
  }
}
```

#### エラーレスポンス
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "入力値が不正です",
    "details": [
      {
        "field": "email",
        "message": "有効なメールアドレスを入力してください"
      }
    ]
  }
}
```

### 5. ページネーション
- クエリパラメータ: `?page=1&per_page=20`
- Linkヘッダーで次ページURLを提供
- 合計件数をmetaに含める

### 6. フィルタリング・ソート
- フィルタ: `?status=active&role=admin`
- ソート: `?sort=created_at&order=desc`
- 検索: `?q=keyword`

### 7. バージョニング
- URLパス: `/api/v1/users`（推奨）
- ヘッダー: `Accept: application/vnd.api+json;version=1`

## Output: OpenAPI Specification

設計結果はOpenAPI 3.0形式で出力すること：

```yaml
openapi: 3.0.3
info:
  title: API名
  version: 1.0.0
  description: API説明

servers:
  - url: https://api.example.com/v1

paths:
  /resource:
    get:
      summary: リソース一覧取得
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'

components:
  schemas:
    Resource:
      type: object
      properties:
        id:
          type: string
        created_at:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
```