api-design

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

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. レスポンス形式

成功レスポンス

{
  "data": { ... },
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20
  }
}

エラーレスポンス

{
  "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形式で出力すること：

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