API デザイン パターン

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

アクティブ化するとき

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

リソース デザイン

URL 構造

# リソースは名詞、複数形、小文字、ケバブケース
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

命名規則

# よい
/api/v1/team-members          # 複数単語リソース用ケバブケース
/api/v1/orders?status=active  # フィルタリング用クエリ パラメーター
/api/v1/users/123/orders      # 所有権用のネストされたリソース

# 悪い
/api/v1/getUsers              # URL 内の動詞
/api/v1/user                  # 単数形（複数形を使用）
/api/v1/team_members          # URL 内のスネークケース
/api/v1/users/123/getOrders   # ネストされたリソース内の動詞

HTTP メソッドとステータス コード

メソッド セマンティクス

メソッド	べき等	セーフ	使用対象
GET	はい	はい	リソースを取得
POST	いいえ	いいえ	リソースを作成、アクションをトリガー
PUT	はい	…