はじめに

APIを実装していると、「更新処理って PUT と PATCH どっち使えばいいの？」と迷うことがあります。

なんとなく PUT を使っている人も多いと思いますが、この2つには明確な違いがあります。

結論

こんなユーザーリソースがあるとします。

{
  "id": 1,
  "name": "田中太郎",
  "email": "tanaka@example.com",
  "age": 25
}

PUT は「このリソースを、送ったデータで丸ごと置き換えてください」という意味です。

PUT /users/1

{
  "name": "田中太郎",
  "email": "tanaka-new@example.com",
  "age": 25
}

名前を変えたいだけでも、全フィールドを送る必要があります。

もし age を省略して送ったらどうなるか？

{
  "name": "田中太郎",
  "email": "tanaka-new@example.com"
}

PUT の仕様に忠実に従うなら、age は null やデフォルト値にリセットされます。「送らなかった = そのフィールドは不要」と解釈されるからです。

PATCH は「送ったフィールドだけ更新してください」という意味です。

PATCH /users/1

{
  "email": "tanaka-new@example.com"
}

これで email だけが更新され、name と age はそのまま残ります。

一見シンプルですが、問題があります。

実務ではこっちに寄りがちですが、PATCH にも注意点はあります。

操作	メソッド	例
リソースの作成または完全な置き換え	PUT	ユーザー設定の一括保存
リソースの一部更新	PATCH	プロフィール画像だけ変更

正直なところ、多くのプロジェクトでは PATCH を中心に使い、PUT はほとんど使わない というケースが多いです。

「名前だけ変えたい」「ステータスだけ更新したい」のように、一部のフィールドだけを更新する場面の方が圧倒的に多いからです。