--- title: "PUT vs PATCH: Which One Should You Use?" url: https://apyhub.com/blog/put-vs-patch-which-one-should-you-use author: ApyHub published: 2026-09-09T08:22:07.792965Z tags: [engineering] --- # PUT vs PATCH: Which One Should You Use? # 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. ## The Difference in Practice A user record on the server: json ```json {"id": 42, "name": "Ada", "email": "ada@example.com", "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. ## The 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. ## Which 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. ## Five Things People Get Wrong 1. **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. 2. **Assuming PATCH is idempotent.** It depends on the operation. Design yours to be idempotent unless you have a reason not to. 3. **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. 4. **Sending a full object to PATCH.** Harmless but pointless. If you have the whole object, PUT expresses the intent better. 5. **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. ## A 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. ## FAQ ### 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. ## Related * [What Is an Idempotent Request?](https://apyhub.com/blog/what-is-an-idempotent-request) - why PUT is safe to retry and POST is not * [405 Method Not Allowed](https://apyhub.com/blog/405-method-not-allowed) - when the method is not permitted at all * [API Fundamentals](https://apyhub.com/blog/api-fundamentals-what-an-api-is-and-how-to-use-one-without-writing-code) - HTTP methods from scratch Source: [RFC 9110, section 9.2.2](https://www.rfc-editor.org/rfc/rfc9110.html) *** ## About ApyHub [ApyHub](https://apyhub.com/) is a curated API catalog for developers, teams and AI agents: [file conversion](https://apyhub.com/catalog/file-conversion), [data validation](https://apyhub.com/catalog/data-validation), [OCR and extraction](https://apyhub.com/catalog/artificial-intelligence) and more across 20 categories. One key covers all of it, every endpoint is [MCP-ready](https://apyhub.com/mcp) 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**](https://apyhub.com/catalog) | [**Get a free API key**](https://apyhub.com/auth/signup) - no credit card required.