RESTful API チートシート

REST（Representational State Transfer）は、HTTP 上でネットワーク化された Web API サービスを設計するためのアーキテクチャスタイルです。

HTTP メソッドとセマンティクス

---

よく使われる HTTP レスポンスステータスコード

成功 (2xx)

• 200 OK: リクエスト成功（ボディに表現が含まれます）。
• 201 Created: リソースの作成に成功（Location ヘッダーで URI を通知）。
• 202 Accepted: 非同期処理としてリクエストを受け付けました。
• 204 No Content: 処理は成功し、レスポンスボディはありません（DELETE で一般的）。

クライアントエラー (4xx)

• 400 Bad Request: 不正な構文、無効なパラメータ、またはバリデーション失敗。
• 401 Unauthorized: 認証情報が不足しているか無効です。
• 403 Forbidden: 認証済みですが、リソースへのアクセス権限がありません。
• 404 Not Found: リソースの URI が存在しません。
• 409 Conflict: 現在のリソース状態と競合しています（例：一意キーの重複）。
• 422 Unprocessable Entity: 構文は正しいがドメインの意味的バリデーションに失敗しました。
• 429 Too Many Requests: レート制限を超過しました。

サーバーエラー (5xx)

• 500 Internal Server Error: サーバー側の汎用未処理エラー。
• 502 Bad Gateway: アップストリームサーバーが無効なレスポンスを返しました。
• 503 Service Unavailable: サーバーが過負荷またはメンテナンス中です。

---

標準 JSON エラーエンベロープ

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The email address provided is already registered.",
    "details": [
      {
        "field": "email",
        "issue": "unique_constraint_violated"
      }
    ]
  }
}

---

リファレンス

• HTTP ステータスコード チートシート
• RFC 9110: HTTP セマンティクス