api-design

name	api-design
description	REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs.
origin	ECC

API Design Patterns

一貫性があり開発者フレンドリーな REST API を設計するための規約とベストプラクティスです。

起動条件

• 新しい API エンドポイントを設計する場合
• 既存の API コントラクトをレビューする場合
• ページネーション、フィルタリング、ソートを追加する場合
• API のエラーハンドリングを実装する場合
• API バージョニング戦略を計画する場合
• パブリックまたはパートナー向け API を構築する場合

Resource Design

URL 構造

# リソースは名詞、複数形、小文字、kebab-case
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PUT    /api/v1/users/:id
PATCH  /api/v1/users/:id
DELETE /api/v1/users/:id

# リレーションシップのためのサブリソース
GET    /api/v1/users/:id/orders
POST   /api/v1/users/:id/orders

# CRUD にマッピングされないアクション（動詞は控えめに使用）
POST   /api/v1/orders/:id/cancel
POST   /api/v1/auth/login
POST   /api/v1/auth/refresh

命名ルール

# GOOD
/api/v1/team-members          # 複数語のリソースには kebab-case
/api/v1/orders?status=active  # フィルタリングにはクエリパラメータ
/api/v1/users/123/orders      # 所有関係にはネストされたリソース

# BAD
/api/v1/getUsers              # URL に動詞
/api/v1/user                  # 単数形（複数形を使用）
/api/v1/team_members          # URL に snake_case
/api/v1/users/123/getOrders   # ネストされたリソースに動詞

HTTP Methods とステータスコード

メソッドのセマンティクス

メソッド	冪等性	安全性	用途
GET	あり	あり	リソースの取得
POST	なし	なし