PUT vs PATCH: Which One Should You Use?

PUT replaces an entire resource. PATCH updates part of one.

Send a PUT and whatever you send becomes the resource. Fields you leave out get removed or reset. Send a PATCH and only the fields you include change; everything else stays as it was.

That single difference drives everything else about choosing between them.

01The Difference in Practice

A user record on the server:

json

· json

{"id": 42, "name": "Ada", "email": "[email protected]", "role": "admin"}

PUT with a partial payload:

http

PUT /users/42
{"name": "Ada Lovelace"}

A correctly implemented PUT replaces the resource. The email and role are gone, because you did not send them. This is the single most common PUT bug in production.

PATCH with the same payload:

http

PATCH /users/42
{"name": "Ada Lovelace"}

Only the name changes. Email and role are untouched.

If you want PUT to work here, you send the whole object every time, including the fields you are not changing.

02The Idempotency Difference

PUT is idempotent. PATCH is not necessarily.

RFC 9110 lists PUT, DELETE and the safe methods as idempotent, meaning repeating the request has the same effect as sending it once. Send the same PUT five times and the resource ends up in the same state.

PATCH is not on that list. Whether a PATCH is idempotent depends entirely on what the patch does. {"name": "Ada"} is idempotent, since applying it repeatedly gives the same result. {"op": "increment", "field": "views"} is not, and running it five times increments five times.

This matters for retries. A client can safely retry a PUT after a network failure. Retrying a PATCH may double-apply the change, so it needs an idempotency key or a check that the original never landed.

03Which To Use

Situation	Method
Updating one or two fields on a large object	PATCH
Replacing a resource wholesale	PUT
Creating a resource at a URL the client chooses	PUT
The client does not have the full current state	PATCH
You need safe automatic retries	PUT
Bandwidth matters and objects are large	PATCH
Concurrent edits to different fields	PATCH

That last row is underrated. If two clients PUT the same object at once, the second overwrites the first entirely, including fields the second client never intended to touch. Two PATCHes to different fields merge cleanly.

04Five Things People Get Wrong

Treating PUT as a partial update. Plenty of APIs accept a partial PUT and merge it. That is convenient and it is not what PUT means, and it surprises anyone reading the spec.
Assuming PATCH is idempotent. It depends on the operation. Design yours to be idempotent unless you have a reason not to.
Forgetting PUT can create. PUT to a URL that does not exist should create the resource there, returning 201. POST creates at a server-chosen URL; PUT creates at a client-chosen one.
Sending a full object to PATCH. Harmless but pointless. If you have the whole object, PUT expresses the intent better.
Ignoring the PATCH format. RFC 5789 defines PATCH but not the patch document format. JSON Merge Patch (RFC 7386) and JSON Patch (RFC 6902) are two different standards, and your API must declare which it accepts.

05A Note on Content Types

Because PATCH has no single format, the Content-Type header carries real meaning.

JSON Merge Patch (application/merge-patch+json) looks like the object with only the changed fields. A null value deletes a field.

JSON Patch (application/json-patch+json) is an array of operations: add, remove, replace, move, copy, test. More powerful, more verbose.

Most APIs describing themselves as accepting PATCH actually accept plain application/json with merge semantics. That is fine, and it should be documented, because a client sending JSON Patch to a merge endpoint gets a confusing result rather than an error.

06FAQ

What is the difference between PUT and PATCH?

PUT replaces the whole resource with what you send, so omitted fields are removed. PATCH updates only the fields you include and leaves the rest alone.

Is PUT idempotent?

Yes. RFC 9110 lists PUT among the idempotent methods, so sending the same PUT repeatedly leaves the resource in the same state. That makes it safe to retry automatically after a network failure.

Is PATCH idempotent?

Not necessarily. It depends on the operation. Setting a field to a value is idempotent; incrementing a counter is not. Design patches to be idempotent where you can, and use an idempotency key where you cannot.

Can PUT create a resource?

Yes. PUT to a URL that does not exist should create the resource at that URL and return 201. The difference from POST is who chooses the URL: the client with PUT, the server with POST.

Why did my PUT delete fields I did not send?

Because that is what PUT means. It replaces the resource with the representation you sent, so anything omitted is gone. Send the full object, or use PATCH.

Which should I use for a partial update?

PATCH. It is the method designed for it, and it avoids the risk of wiping fields you did not include.

What format should a PATCH body be?

Whatever your API documents, since RFC 5789 does not specify one. The two standards are JSON Merge Patch and JSON Patch, and they are not interchangeable. Most APIs use merge semantics with plain JSON.

07Related

What Is an Idempotent Request? - why PUT is safe to retry and POST is not
405 Method Not Allowed - when the method is not permitted at all
API Fundamentals - HTTP methods from scratch

Source: RFC 9110, section 9.2.2

08About ApyHub

ApyHub is a curated API catalog for developers, teams and AI agents: file conversion, data validation, OCR and extraction and more across 20 categories. One key covers all of it, every endpoint is MCP-ready so AI agents can discover and call them directly, and every service page has a playground for testing before you build.

EU-based and EU-hosted, which keeps data residency simple for teams with GDPR obligations.

Browse the catalog | Get a free API key - no credit card required.

PUT vs PATCH: Which One Should You Use?