mcpField
R
rest-api-design

rest-api-design

github.com/secondsky開発240594 回インストール5 週間前に更新
リポジトリ

rest-api-design について

REST APIを設計する開発者向けのガイドです。リソース名、HTTPメソッド、ステータスコード、レスポンス構造、クエリパラメーターに加え、バージョン管理、ページネーション、OpenAPI/Swaggerの文書化も扱います。

主な機能

  1. 01名詞と階層を使ったリソース命名
  2. 02操作に応じたHTTPメソッドの選択
  3. 03適切なステータスコードの選択
  4. 04レスポンス構造とページネーション
  5. 05フィルタリング、ソート、項目選択
  6. 06APIの文書化とバージョン管理

活用シーン

  1. 01リソースパスとエンドポイント操作の設計
  2. 02APIの成功レスポンスとエラーの標準化
  3. 03コレクションへのページネーションとクエリ機能の追加
  4. 04APIのバージョン管理と文書の準備

インストール

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

$npx skills add https://github.com/secondsky/claude-skills --skill rest-api-design

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

詳細

REST API の設計

適切な規約と開発者体験を備えた RESTful API を設計します。

リソースの命名

# Good - nouns, plural, hierarchical
GET    /api/users
GET    /api/users/123
GET    /api/users/123/orders
POST   /api/users
PATCH  /api/users/123
DELETE /api/users/123

# Bad - verbs, actions in URL
GET    /api/getUsers
POST   /api/createUser
POST   /api/users/123/delete

HTTP メソッド

メソッド目的冪等性
GETリソースの読み取りはい
POSTリソースの作成いいえ
PUTリソースの置き換えはい
PATCH部分的な更新はい
DELETEリソースの削除はい

ステータスコード

コード意味用途
200OKGET、PATCH の成功
201作成済みPOST の成功
204コンテンツなしDELETE の成功
400不正なリクエストバリデーションエラー
401認証されていない認証情報がない
403禁止権限が不十分
404見つからないリソースが存在しない
429リクエストが多すぎるレート制限中

レスポンス形式

{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John",
      "email": "[email protected]"
    }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

コレクションのレスポンス

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  },
  "links": {
    "self": "/api/users?page=1",
    "next": "/api/users?page=2"
  }
}

クエリパラメーター

GET /api/products?category=electronics    # Filtering
GET /api/products?sort=-price,name        # Sorting
GET /api/products?page=2&limit=20         # Pagination
GET /api/products?fields=id,name,price    # Field selection

ベストプラクティス

  • リソースには動詞ではなく名詞を使用します
  • URL パス（/api/v1/）で API をバージョン管理します
  • 適切なステータスコードを返します
  • コレクションにはページネーションを含めます
  • OpenAPI/Swagger でドキュメントを作成します

コメント

Markdown 対応