API Design

# 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 | はい | いいえ | リソースの完全な置換 |
| PATCH | いいえ* | いいえ | リソースの部分的な更新 |
| DELETE | はい | いいえ | リソースを削除 |

*PATCH は適切な実装でべき等にすることができます

### ステータス コード リファレンス