PUT vs PATCH: The Difference in REST APIs, with Examples

PUT vs PATCH: The Difference in REST APIs, with Examples

Updated 30 September 2026. Merged with our shorter PUT vs PATCH guide, with a new section on common mistakes.

01Introduction

The difference between PUT and PATCH is scope. PUT replaces the entire resource with the body you send, and PATCH changes only the fields you include.

That one difference decides what happens to fields you leave out, whether a request is safe to retry, and which errors your clients will see. This guide walks through each with request examples you can copy, then gives you a short rule for choosing.

If you are new to APIs, start with our beginner's guide to APIs and come back. Everything below assumes you know what a request body is. If that term is new, this explainer on payloads covers it in five minutes.

02PUT vs PATCH at a glance

All the examples below use this user resource:

{
  "id": 123,
  "name": "Alice",
  "plan": "starter",
  "timezone": "Europe/Amsterdam"
}

03What is PUT in a REST API?

PUT sends a complete replacement for the resource at a URL. The server stores what you send as the new version, in full.

To move Alice to the pro plan with PUT, you send every field, including the ones that did not change:

PUT /users/123 HTTP/1.1
Content-Type: application/json
 
{
  "name": "Alice",
  "plan": "pro",
  "timezone": "Europe/Amsterdam"
}

{
  "id": 123,
  "name": "Alice",
  "plan": "pro",
  "timezone": "Europe/Amsterdam"
}

Leave timezone out and the server has three options: reset it to a default, remove it, or reject the request with 400 or 422. All three are valid PUT behavior. Your API documentation should say which one yours does, because clients cannot guess.

PUT is idempotent. Sending the same PUT once or ten times leaves the resource in the same state, which is why clients and proxies can retry it after a timeout.

04What is PATCH in a REST API?

PATCH sends a set of changes. The server applies them to the current version and leaves every other field untouched.

The same plan change with PATCH:

PATCH /users/123 HTTP/1.1
Content-Type: application/merge-patch+json
 
{
  "plan": "pro"
}

{
  "id": 123,
  "name": "Alice",
  "plan": "pro",
  "timezone": "Europe/Amsterdam"
}

The request body is one field instead of three. On a resource with 40 fields, that difference is the reason PATCH exists.

The catch is idempotency. RFC 5789 states that PATCH is neither safe nor idempotent by default, although a PATCH request can be written so that it is. The next two sections show where that matters.

05JSON Merge Patch vs JSON Patch

The PATCH method on its own doesn't tell the server how to read your body. The Content-Type does. Two formats cover almost every JSON API.

JSON Merge Patch (RFC 7396)

Content type: application/merge-patch+json. You send a partial copy of the resource. Fields you include are added or replaced, fields set to null are removed, and everything else stays.

To remove Alice's timezone:

PATCH /users/123 HTTP/1.1
Content-Type: application/merge-patch+json
 
{
  "timezone": null
}

Merge Patch is readable and covers most everyday updates. It has two limits, both from RFC 7396: you can't set a field to a literal null, because null means "remove", and arrays are replaced whole, so you can't add one item to a list.

JSON Patch (RFC 6902)

Content type: application/json-patch+json. You send a list of operations: add, remove, replace, move, copy and test.

PATCH /users/123 HTTP/1.1
Content-Type: application/json-patch+json
 
[
  { "op": "test", "path": "/plan", "value": "starter" },
  { "op": "replace", "path": "/plan", "value": "pro" }
]

The test operation makes the whole patch fail if plan is no longer starter. That turns a blind update into a conditional one, and it makes this request safe to retry: the second attempt fails the test instead of changing anything.

JSON Patch can also edit arrays precisely. That is also where PATCH stops being idempotent:

[
  { "op": "add", "path": "/tags/-", "value": "beta" }
]

Send that twice and Alice ends up with two beta tags. See the full format in RFC 6902.

Many APIs that say they accept PATCH actually take plain application/json with merge behavior. That works, as long as the documentation says so: a client sending JSON Patch to a merge endpoint gets a confusing result instead of an error.

06PUT vs POST vs PATCH

POST is the third method people mix up with these two.

A useful shortcut: POST to a collection, PUT and PATCH to a single item.

07Status codes for PUT and PATCH

Servers can advertise which patch formats they accept with the Accept-Patch response header. If a PATCH comes back 415, check that header first.

08Avoiding lost updates

Two clients read Alice's profile. One changes her plan, the other her timezone. With PUT, whoever writes second overwrites the first change without knowing it existed. Two PATCH requests to different fields merge cleanly, which is one reason PATCH suits resources that several clients edit.

The fix for conflicting writes works for both methods: send the version you read with If-Match.

PATCH /users/123 HTTP/1.1
Content-Type: application/merge-patch+json
If-Match: "v7"
 
{
  "plan": "pro"
}

If the resource has changed since version v7, the server answers 412 and nothing is written. The client re-reads and tries again.

09Five common PUT and PATCH mistakes

1. Treating PUT as a partial update. Plenty of APIs accept a partial PUT and merge it. It is convenient, it departs from what PUT means, and it surprises anyone who reads the spec. It is also the most common cause of "my PUT deleted fields" bug reports.
2. Assuming PATCH is idempotent. It depends on the operation. Setting a field to a value is idempotent; incrementing a counter or appending to a list is not. Design your patches to be idempotent unless you have a reason not to.
3. Forgetting PUT can create. A PUT to a URL where nothing exists should create the resource there and return 201. POST creates at a server-chosen URL; PUT creates at a client-chosen one.
4. Sending the full object to PATCH. It works, and it wastes the point of PATCH. If you hold the whole object and mean to replace it, PUT states that intent more clearly.
5. Leaving the PATCH format undocumented. RFC 5789 defines the method and leaves the body format open. JSON Merge Patch and JSON Patch are different standards, so your API must say which one it accepts.

10When to use PUT vs PATCH

Use PUT when:

• The client holds the complete resource, like a settings form that submits every field

• You want safe automatic retries with no extra design work

• The client should be able to create a resource at a URL it chooses Use PATCH when:

• You change one or two fields on a large resource

• Different clients own different fields and should not overwrite each other

• Payload size matters, for example on mobile connections

• The client does not have the full current state of the resource If you support PATCH, pick one format, document it, and return 415 for anything else.

11Why this matters more with AI agents

Agents retry. When a call times out, an agent will often send it again. A PUT survives that. A PATCH that appends to a list or increments a counter does not, and the agent has no way to know the first attempt succeeded. For the full picture, see what an idempotent request is and why retries depend on it.

If agents will call your API, make PATCH requests conditional with If-Match or a JSON Patch test operation, and state each endpoint's retry behavior in the documentation. Knowing how to read API documentation is half of this. Writing docs an agent can act on is the other half.

This is also how ApyHub MCP is built: every endpoint in the catalog is exposed to agents with its full input schema, so an agent can discover, evaluate and call an API directly without a hand-written wrapper or tool definition. For more on connecting agents to APIs, see how to build with AI and APIs.

12Try it on real APIs

The fastest way to make this stick is to send real requests and read real responses. Every API in the ApyHub catalog, over 1,500 endpoints and capabilities and growing, has a "Try it" panel where you can change the body, send the request, and see the status code and response. You can also save requests in Voiden, a free, open-source API client that stores each request as a Markdown file you can keep next to your code. The free tier needs no card.

Create your free ApyHub account →

13Conclusion

PUT replaces, PATCH modifies. PUT is idempotent and easy to retry, but it overwrites anything the client leaves out. PATCH sends less and protects fields the client never touched, but it is only safe to retry if you design it that way.

For most APIs, the practical setup is PUT for full replacements, PATCH with JSON Merge Patch for everyday partial updates, JSON Patch where you need array edits or test conditions, and If-Match on both when more than one client writes to the same resource.

Browse the ApyHub catalog →

14FAQ

What is the difference between PUT and PATCH? PUT replaces the entire resource with the body you send. PATCH applies only the changes you send and leaves other fields as they are.

Is PATCH idempotent? Not by default. RFC 5789 defines PATCH as neither safe nor idempotent. A PATCH that sets a field to a fixed value behaves idempotently, while one that appends to an array or increments a number does not.

Is PUT idempotent? Yes. RFC 9110 defines PUT as idempotent: repeating the same request leaves the resource in the same state as sending it once.

Why did my PUT delete fields I didn't send? Because PUT replaces the resource with the representation you sent, so anything you left out can be reset or removed. Send the full object, or use PATCH for partial changes.

What is the difference between PUT, POST and PATCH? POST creates a resource at a URL the server picks, or triggers an action. PUT creates or fully replaces a resource at a URL the client picks. PATCH partially updates an existing resource.

Can PUT create a new resource? Yes. If nothing exists at the URL, a PUT can create it and the server returns 201 Created.

How do I remove a field with PATCH? With JSON Merge Patch, set the field to null. With JSON Patch, use a remove operation on the field's path.

Should I use JSON Merge Patch or JSON Patch? Use JSON Merge Patch for simple field updates, since it is easier to read and write. Use JSON Patch when you need to edit arrays, or when you want a test operation that makes the update conditional.

Which HTTP status code should a successful PATCH return? 200 OK if you return the updated resource, or 204 No Content if you return nothing.

How can I test PUT and PATCH requests? Use an API client such as Voiden, Postman or Insomnia, or curl from the terminal, and compare the resource before and after each call. Every API in the ApyHub catalog also has a "Try it" panel with the request body, status code and response side by side.

15Related

• 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
• What Is a Bearer Token?: how most of these requests are authenticated

16Sources

• RFC 9110: HTTP Semantics (PUT, idempotent methods)
• RFC 5789: PATCH Method for HTTP
• RFC 7396: JSON Merge Patch
• RFC 6902: JSON Patch

17About ApyHub

ApyHub is a curated API catalog and trusted operational layer for developers and AI agents, with over 1,500 endpoints or capabilities and growing. Teams use the whole catalog through a single subscription priced in atoms, a unit that reflects the actual work each call performs. Every endpoint ships with machine-readable certification aligned with GDPR, SOC 2 and ISO 27001, and is MCP-ready by default, so AI agents can discover and call it through ApyHub MCP without custom wrappers. ApyHub is headquartered in Amsterdam, with offices in the Netherlands, Greece and India, and serves 65,000+ developer workspaces every month. The free tier requires no card. Building an API of your own? Become a provider →