PUT vs PATCH

Both methods modify an existing resource, and they differ in what the body means. A PUT body is the complete new state: fields you leave out are, in principle, removed or reset. A PATCH body is a description of changes, in a format the server documents — a partial object, or a list of operations as in JSON Patch.

How it works

PUT is idempotent by definition: sending the same full representation twice leaves the same result. PATCH is not guaranteed to be, because an operation like "append to this list" or "increment" applied twice does something different from applying it once. That is why PATCH requests in particular benefit from If-Match, so a retried patch can be refused instead of doubled.

The misconception

That PATCH is just "PUT without the fields you did not change". Many APIs implement it that way, but nothing about the method says so — a merge-style PATCH and a JSON Patch document are both PATCH, with very different semantics. And many "PUT" endpoints in practice merge rather than replace, so test what yours actually does with a missing field.

Try it here

The Pizza API takes a partial update on PATCH /pizza/v1/orders/{id}, and the Protocol Lab accepts an RFC 6902 JSON Patch on PATCH /protocol/v1/documents/{id}; the character PUT endpoints replace and check If-Match.

Sources

Other terms

JSON Patch — A standard format (RFC 6902) for describing changes to a JSON document as a list of operations.
Safe and idempotent methods — Two independent properties of HTTP methods that decide what a client is allowed to retry.
ETag — An opaque version identifier for a representation, used to avoid re-sending it and to detect conflicting writes.
Retry-After — A response header telling the client how long to wait before trying again, in seconds or as a date.
Exponential backoff — A retry strategy where each wait is longer than the last, with randomness added so clients do not retry in sync.
Request timeout — The maximum time a client will wait for a response before abandoning the request.

All glossary terms · Testing techniques · All 39 mock REST APIs

Last updated 16 October 2026