REST API設計でよくある間違い：PUT/PATCH・ステータスコード・命名規則

概要¶

「ほとんどの API は REST ではなく、ただの HTTP エンドポイントだ」という指摘から始まる、実務でよく見る REST API 設計ミスの解説。

詳細¶

間違い 1：PUT を PATCH の代わりに使う¶

# 悪い例: ユーザーのメールだけ更新したいのに PUT を使う
PUT /users/123
{
  "name": "Taro",       ← 変えるつもりがないのに全フィールドが必要
  "email": "new@example.com",
  "role": "admin"
}

# 正しい: 部分更新には PATCH
PATCH /users/123
{
  "email": "new@example.com"   ← 変えたいフィールドだけ
}

ルール: - PUT = リソース全体を置き換える（全フィールド必須） - PATCH = 一部フィールドだけ更新する

間違い 2：HTTP ステータスコードを無視する¶

# 悪い例: 全部 200 で返す
HTTP/1.1 200 OK
{ "error": "User not found" }  ← エラーなのに 200？

# 正しい
HTTP/1.1 404 Not Found
{ "message": "User not found", "code": "USER_NOT_FOUND" }

よく使うステータスコード:

200 OK           → 正常レスポンス（GET・PUT・PATCH 成功）
201 Created      → リソース作成成功（POST）
204 No Content   → 削除成功（DELETE）
400 Bad Request  → リクエストの形式が不正
401 Unauthorized → 認証が必要
403 Forbidden    → 権限なし（認証済みだが操作不可）
404 Not Found    → リソースが存在しない
409 Conflict     → 競合（重複など）
422 Unprocessable → バリデーションエラー
429 Too Many Requests → レートリミット超過
500 Internal Server Error → サーバーエラー

間違い 3：命名規則が REST らしくない¶

# 悪い例（動詞 + リソース名）
GET /getUserData
POST /createUser
DELETE /deleteUser/123
GET /api/getActiveOrders

# 正しい（名詞のリソースに HTTP メソッドで動作を表現）
GET    /users/123
POST   /users
DELETE /users/123
GET    /orders?status=active   ← フィルタはクエリパラメータ

間違い 4：バージョニングをしない¶

# バージョニングなし → 破壊的変更を出せない
GET /users/123

# バージョニングあり → v1 を壊さずに v2 で変更可能
GET /api/v1/users/123
GET /api/v2/users/123

なぜ重要か / いつ使うか¶

新しい API を設計するとき
コードレビューで API 設計をチェックするとき
面接で「REST API の設計について」聞かれたとき