PUT vs PATCH — 完全置換 vs 部分更新

PUT: リソースの完全置換

PUTはターゲットURIのリソース全体をリクエストボディで置き換えます。リソースが存在しない場合、PUTはそれを作成することがあります。変更されていないフィールドも含め、すべてのフィールドを送信する必要があります。

PUT /api/users/42 HTTP/1.1
Content-Type: application/json

{
  "name": "Charlie Updated",
  "email": "charlie@example.com",
  "role": "admin",
  "bio": "DevOpsエンジニア"
}

bioフィールドを省略すると、PUTはリソース全体を置き換えるため、そのフィールドは削除されます（nullまたはデフォルトに設定）。

PATCH: 部分変更

PATCHは部分的な変更を適用します。変更したいフィールドのみを含めます：

PATCH /api/users/42 HTTP/1.1
Content-Type: application/json

{
  "role": "admin"
}

roleフィールドのみが更新され、他のフィールドはすべて変更されません。

比較表

観点	PUT	PATCH
ペイロード	完全なリソース	変更されたフィールドのみ
欠落フィールド	デフォルトにリセット	変更なし
冪等	はい	保証されない
リソース作成	はい（既知のURIで）	通常いいえ
RFC	RFC 9110	RFC 5789

使い分け

PUTを使用する場合：

• クライアントが完全な更新済みリソースを持っている
• 決定的で冪等な更新が必要
• ペイロードからリソースを完全に再構築できる

PATCHを使用する場合：

• 1〜2個のフィールドのみを変更する必要がある
• 完全なリソースの送信が無駄になる
• リソースが大きいまたは複雑

JSON Merge Patch vs JSON Patch

PATCHには2つの一般的なコンテンツタイプがあります：

1. JSON Merge Patch (application/merge-patch+json) — 変更されたフィールドのみを含むJSONオブジェクトを送信；nullでフィールドを削除
2. JSON Patch (application/json-patch+json) — 操作（add, remove, replace, move, copy, test）の配列を送信