冪等なHTTPメソッドの理解

冪等性とは？

HTTPメソッドが冪等であるとは、同じリクエストを1回以上行っても同じサーバー状態になることです。レスポンスは異なる場合があります（例：最初のDELETEは200を返し、2回目は404を返す）が、リソースの状態は同じままです。

冪等性マトリクス

メソッド	冪等	説明
GET	はい	データの読み取りは状態を変更しない
HEAD	はい	GETと同じでボディなし
PUT	はい	同じデータでリソースを置き換えると同じ結果
DELETE	はい	既に削除されたリソースの削除はno-op
OPTIONS	はい	機能の記述は状態を変更しない
TRACE	はい	リクエストのエコーは状態を変更しない
POST	いいえ	各呼び出しで新しいリソースが作成される可能性
PATCH	いいえ	部分更新は累積的な効果を持つ可能性
CONNECT	いいえ	各トンネル確立は新しい接続

冪等性が重要な理由

1. ネットワークリトライ — リクエストがタイムアウトした場合、冪等なメソッドは副作用なく安全にリトライできる
2. ロードバランサー — 失敗したリクエストを別のサーバーでリトライできる
3. クライアントの信頼性 — モバイルアプリやSPAは接続不良時にリトライできる
4. キャッシュ — 冪等なメソッドはレスポンスキャッシュの候補

Idempotency KeyによるPOSTの冪等化

多くの決済API（Stripe、PayPal）はIdempotency-Keyヘッダーを使用します：

POST /api/payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: unique-uuid-per-request

{ "amount": 1000, "currency": "USD" }

同じキーが再度送信されると、サーバーは支払いを二重処理せずに元のレスポンスを返します。

冪等性 vs 安全性

すべての安全なメソッドは冪等ですが、すべての冪等なメソッドが安全というわけではありません。PUTとDELETEはサーバーの状態を変更します（安全ではない）が、繰り返しても同じ結果を生成します（冪等）。