mcpField

api-design

github.com/eddiebe147開発40 回インストール
リポジトリ

api-design について

エンドポイント、リクエストとレスポンスの形式、ステータスコード、バージョン管理、セキュリティを扱う、開発者向けのREST API設計リファレンスです。

主な機能

  1. 01HTTPメソッドとURLの指針
  2. 02ステータスコードの指針
  3. 03コレクションとエラーの形式
  4. 04フィルタリング、ソート、ページネーション
  5. 05冪等性とバージョン管理
  6. 06入力検証とセキュリティの指針

活用シーン

  1. 01CRUDエンドポイントの設計
  2. 02APIエラーレスポンスの標準化
  3. 03ページネーションと絞り込みの追加
  4. 04APIの破壊的変更の計画

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/eddiebe147/claude-settings --skill api-design

インストール後、Claude Code で/api-designを入力して読み込まれたか確認します。

詳細

REST API 設計原則

URL 構造

GET    /api/v1/resources           # List all
GET    /api/v1/resources/{id}      # Get one
POST   /api/v1/resources           # Create
PUT    /api/v1/resources/{id}      # Replace
PATCH  /api/v1/resources/{id}      # Partial update
DELETE /api/v1/resources/{id}      # Delete

# Nested resources
GET    /api/v1/parents/{id}/children
POST   /api/v1/parents/{id}/children

HTTP ステータスコード

コード意味使用する場面
200OKGET、PUT、PATCH が成功した場合
201作成済みPOST が成功した場合（新しいリソース）
204コンテンツなしDELETE が成功した場合
400不正なリクエスト検証エラー、不正な形式のリクエスト
401認証されていません認証情報がない、または無効な場合
403禁止認証は有効だが、権限がない場合
404見つかりませんリソースが存在しない場合
409競合重複、状態の競合
422処理できません意味上のエラー
500サーバーエラー予期しないエラー

リクエスト／レスポンスの設計

コレクションのレスポンス
{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 150,
    "totalPages": 8
  }
}
単一リソースのレスポンス
{
  "id": "uuid",
  "name": "Resource Name",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:00:00Z"
}
エラーレスポンス
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Name is required",
    "details": [
      {"field": "name", "message": "must not be blank"}
    ]
  }
}

クエリパラメーター

# Filtering
GET /api/v1/resources?status=active&type=premium

# Sorting
GET /api/v1/resources?sort=createdAt,desc

# Pagination
GET /api/v1/resources?page=1&pageSize=20

# Field selection
GET /api/v1/resources?fields=id,name,status

# Search
GET /api/v1/resources?search=query

冪等性

  • 一意の識別子を使う POST では、重複がある場合に既存のリソースを返します（200）
  • PUT／DELETE は冪等にします
  • 作成済みか既存かを示すには、Pair<Result, Boolean> パターンを使用します

バージョン管理

  • URL パスによるバージョン管理を使用します：/api/v1/、/api/v2/
  • 破壊的変更を行う場合はバージョンを更新します
  • 移行期間中は旧バージョンをサポートします

セキュリティ上の考慮事項

  • API の境界で常に入力を検証します
  • パラメーター化クエリを使用します（JOOQ が処理します）
  • サービス層で認可を確認します
  • 内部 ID や機密データを決して公開しません
  • 公開エンドポイントにはレート制限を設けます

コメント

Markdown 対応