REST と HTTP の基本

リソース指向設計

REST（Representational State Transfer） は、Web API を設計するためのアーキテクチャスタイルです。 REST では、操作対象を リソース として URI で識別し、HTTP メソッドで操作を表現します。 リソースは名詞で表し、動詞は使わないのが原則です。

たとえば「ユーザー一覧の取得」は GET /users、「ユーザーの作成」は POST /users のように表現します。 個別リソースへのアクセスには GET /users/{id} のようにパスパラメータを用います。

HTTP メソッドと冪等性

主要な HTTP メソッドは以下のとおりです。

冪等性（idempotency） とは、同じリクエストを何度送っても結果が変わらない性質です。 GET・PUT・DELETE は冪等であり、リトライ時に副作用が発生しません。 POST は冪等ではないため、重複送信を防ぐ仕組み（冪等キーなど）が別途必要です。

ステータスコード

HTTP レスポンスの ステータスコード は、処理結果をクライアントに伝える標準的な手段です。

• 2xx — 成功（200 OK, 201 Created, 204 No Content）
• 4xx — クライアントエラー（400 Bad Request, 401 Unauthorized, 404 Not Found）
• 5xx — サーバーエラー（500 Internal Server Error, 503 Service Unavailable）

意味のあるステータスコードを返すことで、クライアントはレスポンスボディを解析せずにエラーハンドリングできます。

コンテントネゴシエーション

コンテントネゴシエーション は、クライアントとサーバーがレスポンス形式を合意する仕組みです。 クライアントは Accept ヘッダーで希望するメディアタイプ（例: application/json）を指定します。 サーバーは Content-Type ヘッダーで実際の形式を返します。

GET /users/42 HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 42, "name": "usaneko"}