PUTとPATCHの違いとは？API更新処理の使い分けを具体例で解説

ITインフラ
この記事は約12分で読めます。

この記事の最終更新日: 2026年5月22日

Web APIでデータを更新するとき、よく使われるHTTPメソッドに PUT と PATCH があります。

どちらも「更新」に使われるため、初心者のうちは次のように迷いやすいです。

ユーザー情報を更新するAPIはPUT？PATCH？
一部の項目だけ変更するならPATCH？
PUTでも一部更新していいの？

結論から言うと、基本的な使い分けは次の通りです。

メソッド主な用途
PUTリソース全体を置き換える
PATCHリソースの一部を変更する

この記事では、PUTとPATCHの違いを、API設計の具体例を使ってわかりやすく解説します。

PUTとは？

PUTは、指定したリソースを 丸ごと置き換える ためのHTTPメソッドです。

たとえば、ユーザー情報を更新するAPIがあるとします。

PUT /users/1

このAPIに対して、次のようなリクエストを送ります。

{
  "name": "山田太郎",
  "email": "yamada@example.com",
  "age": 30
}

この場合、/users/1 というユーザー情報全体を、このJSONの内容で置き換えるイメージです。

つまり、PUTでは基本的に「更新後の完成形」を送ります。

PATCHとは？

PATCHは、指定したリソースの 一部だけを変更する ためのHTTPメソッドです。

たとえば、ユーザーの年齢だけを変更したい場合は、次のように送ります。

PATCH /users/1


{
  "age": 31
}

この場合、name や email は変更せず、age だけを更新するという意味になります。

PATCHは「差分更新」に向いています。

PUTとPATCHの一番大きな違い

PUTとPATCHの違いを一言でまとめると、次のようになります。

PUTは「全体を置き換える」
PATCHは「一部を変更する」

たとえば、現在のユーザー情報が次の状態だったとします。

{
  "id": 1,
  "name": "山田太郎",
  "email": "yamada@example.com",
  "age": 30
}

ここで年齢だけを31歳に変更したい場合を考えます。

PUTで更新する場合

PUTを使う場合は、基本的に更新後のリソース全体を送ります。

PUT /users/1


{
  "name": "山田太郎",
  "email": "yamada@example.com",
  "age": 31
}

更新後の状態は次のようになります。

{
  "id": 1,
  "name": "山田太郎",
  "email": "yamada@example.com",
  "age": 31
}

PUTでは、年齢だけを変えたい場合でも、name や email も含めて送るのが基本です。

PATCHで更新する場合

PATCHを使う場合は、変更したい項目だけを送ります。

PATCH /users/1


{
  "age": 31
}

更新後の状態は次のようになります。

{
  "id": 1,
  "name": "山田太郎",
  "email": "yamada@example.com",
  "age": 31
}

name と email は送っていませんが、既存の値がそのまま残ります。

PUTで一部だけ送るとどうなる？

ここが実務でよく混乱するポイントです。

たとえば、PUTで次のようなリクエストを送ったとします。

PUT /users/1


{
  "age": 31
}

PUTは本来「全体を置き換える」メソッドなので、考え方としては次のような状態になる可能性があります。

{
  "id": 1,
  "name": null,
  "email": null,
  "age": 31
}

または、APIの実装によってはバリデーションエラーになることもあります。

{
  "message": "nameは必須です",
  "errors": {
    "name": ["nameは必須項目です"],
    "email": ["emailは必須項目です"]
  }
}

ただし、実際の現場ではPUTでも一部更新のように実装されているAPIもあります。

そのため、重要なのは「HTTPメソッドの意味」と「そのAPIの仕様」が一致していることです。

実務での使い分け

実務では、次のように使い分けるとわかりやすいです。

やりたいこと適したメソッド
ユーザー情報全体を更新するPUT
プロフィール全体を保存し直すPUT
設定情報を丸ごと更新するPUT
名前だけ変更するPATCH
ステータスだけ変更するPATCH
通知設定の一部だけ変更するPATCH
有効・無効フラグだけ切り替えるPATCH

具体例1：プロフィール編集画面

プロフィール編集画面で、名前・メールアドレス・自己紹介文などをまとめて編集するとします。

{
  "name": "山田太郎",
  "email": "yamada@example.com",
  "bio": "Webエンジニアです。"
}

このように、画面上でプロフィール全体を編集して保存する場合は、PUTが向いています。

PUT /users/1/profile


{
  "name": "山田太郎",
  "email": "yamada@example.com",
  "bio": "Webエンジニアです。"
}

画面のフォーム全体をそのまま送信し、プロフィール全体を更新するイメージです。

具体例2：ユーザー名だけ変更する

ユーザー名だけを変更するAPIであれば、PATCHが向いています。

PATCH /users/1


{
  "name": "佐藤太郎"
}

このAPIでは、name だけを更新し、他の項目は変更しません。

具体例3：タスクの完了状態を変更する

タスク管理アプリで、タスクを完了済みにする場合を考えます。

現在のタスク情報が次の状態だったとします。

{
  "id": 10,
  "title": "請求書を作成する",
  "description": "月末までに対応",
  "is_completed": false
}

完了状態だけを変更したい場合は、PATCHが適しています。

PATCH /tasks/10


{
  "is_completed": true
}

タスク全体ではなく、is_completed だけを変更するためです。

具体例4：商品情報を丸ごと更新する

ECサイトの商品情報を管理するAPIを考えます。

PUT /products/100


{
  "name": "ワイヤレスイヤホン",
  "price": 12800,
  "stock": 50,
  "description": "ノイズキャンセリング対応のイヤホンです。"
}

商品名、価格、在庫数、説明文などをまとめて更新する場合は、PUTが向いています。

管理画面で商品情報を編集し、「保存」ボタンを押すようなケースです。

PUTは冪等、PATCHは必ずしも冪等ではない

PUTとPATCHを理解するうえで、もう一つ重要なのが 冪等性 です。

冪等性とは、同じリクエストを何回実行しても結果が同じになる性質のことです。

PUTは冪等です。

たとえば、次のPUTリクエストを何回送っても、最終的な状態は同じです。

PUT /users/1


{
  "name": "山田太郎",
  "email": "yamada@example.com",
  "age": 31
}

1回送っても、3回送っても、ユーザー情報は同じ状態になります。

一方で、PATCHは設計によって冪等になる場合もあれば、ならない場合もあります。

たとえば、次のようなPATCHは冪等です。

PATCH /users/1


{
  "age": 31
}

何回送っても、age は31のままです。

しかし、次のような「値を増やす」操作は冪等ではありません。

PATCH /articles/1


{
  "increment_view_count": 1
}

この場合、リクエストを送るたびに閲覧数が増えるため、同じ結果にはなりません。

PUTとPATCHのAPI設計例

REST APIとして設計するなら、次のような使い分けが自然です。

ユーザー全体を更新する

PUT /users/{id}

リクエスト例：

{
  "name": "山田太郎",
  "email": "yamada@example.com",
  "age": 31
}

このAPIでは、ユーザー情報全体を更新します。

ユーザーの一部だけ更新する

PATCH /users/{id}

リクエスト例：

{
  "age": 31
}

このAPIでは、指定された項目だけを更新します。

ステータスだけ変更する

PATCH /orders/{id}

リクエスト例：

{
  "status": "shipped"
}

注文全体ではなく、注文ステータスだけを変更するため、PATCHが向いています。

PUTを使うべきケース

PUTは、次のようなケースに向いています。

リソース全体を更新したい場合

たとえば、記事編集画面でタイトル・本文・公開状態などをまとめて保存する場合です。

PUT /articles/1


{
  "title": "PUTとPATCHの違い",
  "body": "本文です。",
  "status": "published"
}

このように、記事全体の更新後の状態を送る場合はPUTが適しています。

クライアントが完全なデータを持っている場合

画面上に更新対象の項目がすべて表示されており、送信時にもすべての値を送れるならPUTが使いやすいです。

更新内容を明確にしたい場合

PUTは「このリソースをこの状態にする」という意味が強いため、APIの意図が明確になります。

PATCHを使うべきケース

PATCHは、次のようなケースに向いています。

一部の項目だけ更新したい場合

名前だけ、ステータスだけ、フラグだけ、表示順だけなど、一部の項目を変更する場合です。

PATCH /users/1


{
  "name": "佐藤太郎"
}

送信データを少なくしたい場合

大きなリソースの一部だけを変更する場合、PATCHなら必要な項目だけを送れます。

たとえば、記事本文が非常に長い場合に、公開ステータスだけ変更したいならPATCHが便利です。

PATCH /articles/1


{
  "status": "published"
}

更新対象が画面の一部分に限定されている場合

たとえば、管理画面で「有効・無効」のスイッチだけを切り替えるようなケースです。

PATCH /users/1


{
  "is_active": false
}

このような小さな更新にはPATCHが向いています。

PUTとPATCHの使い分けで迷ったときの判断基準

迷ったときは、次の基準で考えると判断しやすいです。

更新後の完成形を送るならPUT

クライアントがリソース全体の状態を送るならPUTです。

{
  "name": "山田太郎",
  "email": "yamada@example.com",
  "age": 31
}

これは「ユーザー情報をこの状態にしてください」というリクエストです。

変更したい項目だけ送るならPATCH

クライアントが変更したい項目だけを送るならPATCHです。

{
  "age": 31
}

これは「年齢だけ31に変更してください」というリクエストです。

よくある誤解

誤解1：PUTは更新、PATCHも更新なのでどちらでもいい

どちらも更新に使われますが、意味は異なります。

PUTは全体の置き換え、PATCHは一部変更です。

どちらでも動くように実装することは可能ですが、APIの利用者から見ると仕様がわかりにくくなります。

誤解2：PATCHは必ず1項目だけ更新する

PATCHは「一部更新」ですが、1項目だけに限定されるわけではありません。

たとえば、次のように複数項目をまとめて更新しても問題ありません。

PATCH /users/1


{
  "name": "佐藤太郎",
  "age": 32
}

ポイントは「リソース全体ではなく、変更したい項目だけを送っている」という点です。

誤解3：PUTでは必ず新規作成できる

PUTは、指定したURIのリソースを作成または置き換える用途で使われることがあります。

ただし、一般的なWeb APIでは、新規作成にはPOSTを使うことが多いです。

POST /users


{
  "name": "山田太郎",
  "email": "yamada@example.com"
}

一方で、クライアント側がリソースIDを決める設計では、PUTで作成するケースもあります。

PUT /users/1


{
  "name": "山田太郎",
  "email": "yamada@example.com"
}

ただし、実務では「作成はPOST、更新はPUTまたはPATCH」と考えるとわかりやすいです。

実装時の注意点

PUTとPATCHを使い分けるときは、API仕様として次の点を明確にしておくことが重要です。

PUTで未指定の項目をどう扱うか

PUTで一部の項目が送られてこなかった場合、次のどちらにするのか決めておく必要があります。

  • バリデーションエラーにする
  • 未指定項目をnullや初期値として扱う
  • 既存値を維持する

ただし、既存値を維持するならPATCHに近い挙動になります。

そのため、PUTでは基本的に必要な項目をすべて送る設計にした方が自然です。

PATCHでnullをどう扱うか

PATCHでは、null の扱いに注意が必要です。

たとえば、次のリクエストがあったとします。

{
  "bio": null
}

このとき、bio を空にしたいのか、更新対象から除外したいのかを明確にする必要があります。

一般的には、PATCHでキーが存在している場合は「その値に更新する」と考えます。

つまり、bio: null が送られてきたら、bio を null に更新するという仕様です。

一方で、キー自体が存在しない場合は更新しません。

{
  "name": "山田太郎"
}

この場合、bio は変更しません。

Laravelで考えるPUTとPATCHの例

LaravelでAPIを作る場合、ルーティングは次のように書けます。

Route::put('/users/{user}', [UserController::class, 'update']);
Route::patch('/users/{user}', [UserController::class, 'partialUpdate']);

PUTでは、必須項目をすべてバリデーションします。

public function update(Request $request, User $user)
{
    $validated = $request->validate([
        'name' => ['required', 'string', 'max:255'],
        'email' => ['required', 'email'],
        'age' => ['required', 'integer'],
    ]);

    $user->update($validated);

    return response()->json($user);
}

PATCHでは、送られてきた項目だけをバリデーションします。

public function partialUpdate(Request $request, User $user)
{
    $validated = $request->validate([
        'name' => ['sometimes', 'string', 'max:255'],
        'email' => ['sometimes', 'email'],
        'age' => ['sometimes', 'integer'],
    ]);

    $user->update($validated);

    return response()->json($user);
}

Laravelでは、PATCHのような一部更新には sometimes を使うと相性が良いです。

required は「必ず必要」、sometimes は「送られてきた場合だけ検証する」という違いがあります。

API設計としておすすめの方針

実務では、次のようなルールにしておくとわかりやすいです。

POST   /users      ユーザーを作成する
GET    /users/1    ユーザーを取得する
PUT    /users/1    ユーザー全体を更新する
PATCH  /users/1    ユーザーの一部を更新する
DELETE /users/1    ユーザーを削除する

このように役割を分けておくと、API利用者にとっても理解しやすくなります。

まとめ

PUTとPATCHはどちらも更新処理に使われるHTTPメソッドですが、意味は異なります。

メソッド意味送るデータ主な用途
PUT全体を置き換える更新後のリソース全体全体更新
PATCH一部を変更する変更したい項目だけ部分更新

使い分けの判断基準はシンプルです。

更新後の完成形を送るならPUT
変更したい項目だけ送るならPATCH

PUTとPATCHを適切に使い分けることで、APIの意図が明確になり、フロントエンド側からもバックエンド側からも扱いやすい設計になります。

コメント

タイトルとURLをコピーしました