第 2 章

HTTPメソッドとステータスコードの使い分け

RESTful APIの強みは、HTTPプロトコルの標準仕様（メソッドやステータスコード）をそのまま利用することで、自己記述的（自己解決的）なAPIを実現できる点にあります。本章では、HTTPメソッドとステータスコードの正しい使い分けについて解説します。

1. HTTPメソッドの役割と性質

APIクライアントがどのような操作を行いたいかは、HTTPメソッドによって表されます。

主要なHTTPメソッド

GET: リソースを取得します。リクエストボディを持ちません。
POST: 新しいリソースを作成します。または、冪等（べきとう）ではない汎用的な処理を実行します。
PUT: 既存のリソースを完全に置き換えます。指定されたURIにリソースが存在しない場合は、新規作成します。
PATCH: 既存のリソースを部分的に更新します。
DELETE: リソースを削除します。

「安全性」と「冪等性（べきとうせい）」

APIの信頼性を設計する上で、以下の2つの概念を理解することが不可欠です。

安全性 (Safety): 操作を実行しても、サーバー上のリソースの状態が変化しない性質（読み取り専用）。
冪等性 (Idempotency): 同じ操作を1回実行しても、何回実行しても、サーバー上の結果が同じになる性質。

メソッド	安全性	冪等性	動作の特徴
`GET`	◯	◯	何度取得してもデータは変わらない
`POST`	×	×	複数回送信すると、その分リソースが新しく重複作成される
`PUT`	×	◯	完全に上書きするため、何回送信しても同じ状態に収束する
`PATCH`	×	×	部分更新のため、加算処理などを行うと結果が変わる場合がある
`DELETE`	×	◯	2回目以降の削除は「既に存在しない」ため、リソースの状態は変わらない

2. HTTPステータスコードの設計

サーバーは、処理結果をHTTPステータスコードを使ってクライアントに通知します。これにより、クライアントはレスポンスボディをパースする前に処理の成否を判断できます。

代表的なステータスコード一覧

2xx Success（成功）

200 OK: リクエスト成功。主に GET や PATCH などの成功時に返します。
201 Created: リクエストによりリソースの作成が成功。主に POST 時に返します。レスポンスには作成されたオブジェクトを含めるか、Location ヘッダーに新URIを含めます。
204 No Content: リクエストは成功したが、返すべきレスポンスボディがない。主に DELETE や一部の更新成功時に返します。

4xx Client Error（クライアント側の問題）

400 Bad Request: 入力バリデーションエラーなど、クライアントのリクエスト形式が不正。
401 Unauthorized: 認証情報がない、または無効。ログインが必要であることを示します。
403 Forbidden: 認証されているが、そのリソースに対するアクセス権限がない。
404 Not Found: 指定されたURIのリソースが存在しない。

5xx Server Error（サーバー側の問題）

500 Internal Server Error: サーバー内部で予期しない例外が発生（バグなど）。
503 Service Unavailable: サーバーの過負荷やメンテナンス中で処理が一時的に実行不可。

3. 統一されたエラーレスポンス

エラー（4xx, 5xx）を返す際は、ステータスコードだけでなく、クライアントがプログラムでハンドリングしやすいよう、統一されたJSON形式のエラー情報をボディに含めるのが良いプラクティスです。

良いエラーレスポンスの例

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "リクエストパラメータの検証に失敗しました。",
    "details": [
      {
        "field": "email",
        "message": "有効なメールアドレスの形式で入力してください。"
      }
    ]
  }
}

このように構造化されたエラー情報を返すことで、フロントエンドでのユーザー向けメッセージの出し分けが容易になります。

まとめ

GET/PUT/DELETE は 冪等（べきとう） に設計する。
ステータスコード を適切に使い分けることで、クライアントに明確な結果を提示する。
エラー発生時は、フロントエンドが処理しやすい 統一されたエラーフォーマット を返す。