How do the HTTP methods PUT and PATCH differ in what the request body means, and what does RFC 5789 require of a PATCH payload?

## The semantic split RFC 9110 defines **PUT** as a request that the target resource's state **be created or replaced with the state defined by the representation enclosed in the request**. The body is a complete representation, in the same media type the resource speaks. Successful PUT means: a later GET should return (semantically) what you just sent. **PATCH**, defined separately in RFC 5789, carries a **description of changes**. The body is a *patch document* — a set of instructions, not a resource. That is why PATCH needs its own media types: without one, the server cannot know how to interpret the payload. ## The partial-PUT trap Send `PUT /users/1` with `{"email":"[email protected]"}` to a user resource that also has `name` and `phone`, and a strictly conformant server will replace the resource, leaving `name` and `phone` absent. Many real servers instead merge, quietly turning PUT into PATCH; the result is a contract nobody can reason about, and the exact same request destroys data on one implementation and not on another. Two defensible positions: implement PUT as a true replacement and document it, or reject bodies that omit required members. Silently merging is the one to argue against. ## JSON Merge Patch (RFC 7386) Media type `application/merge-patch+json`. The document looks like a sparse version of the resource: ``` {"email":"[email protected]", "phone": null} ``` Rules: a member present with a value **sets** it; a member with the value `null` **removes** it; members absent are untouched; arrays and other non-objects **replace** wholesale. Strengths: intuitive, tiny, easy to produce from a form. Limits that matter: - You **cannot set a member to JSON null**, because null is reserved for deletion. - You **cannot edit one element of an array** — you must resend the whole array, which reintroduces the lost-update risk for lists. - There is no way to express a precondition inside the document. ## JSON Patch (RFC 6902) Media type `application/json-patch+json`. The document is an **ordered array of operations**, each addressing a location with a JSON Pointer: ``` [{"op":"replace","path":"/email","value":"[email protected]"}, {"op":"add","path":"/tags/-","value":"vip"}, {"op":"test","path":"/version","value":7}] ``` Operations: `add`, `remove`, `replace`, `move`, `copy`, `test`. `test` is the interesting one — if it fails, the whole patch fails, giving in-document optimistic concurrency. Ordering matters, and the operations must be applied as a unit. Strengths: precise array manipulation, explicit deletes distinct from nulls, and conditional application. Cost: verbose, harder to hand-write, and easier to get wrong. ## Atomicity and error reporting RFC 5789 requires the server to apply the **entire** set of changes atomically: the resource must never be left in a half-patched state. If any operation fails — bad pointer, failed `test`, a resulting document that violates business rules — the server rejects the whole patch and the resource is untouched. Useful statuses: **409 Conflict** when the patch cannot be applied to the current state, **422 Unprocessable Content** when the patch is well-formed but the result would be invalid, **400** when the patch document itself is malformed, and **415 Unsupported Media Type** when the server does not support the offered patch format. ## Idempotency, stated carefully PUT is defined as idempotent: sending the same complete representation twice leaves the same state. PATCH is **not required** to be idempotent — `{"op":"add","path":"/tags/-"}` appends on every application. A merge patch usually *is* idempotent by construction, but that is a property of the specific document, not of the method. Clients that retry a PATCH need either a patch document you know to be idempotent, a `test` operation, or a conditional request. ## Concurrency: pair PATCH with conditional requests Because a patch is computed against a version the client read, it should ideally be applied to that same version. The protocol-level tool is `If-Match` with the entity-tag from the read; if the resource has moved on, the server answers **412 Precondition Failed** and the client re-reads and re-derives the patch. A server that wants to force this can answer unconditional writes with **428 Precondition Required**. JSON Patch's `test` operation is an in-document alternative. ## Discoverability PATCH is optional, so a server advertises it in `Allow` (on OPTIONS or on a 405) and advertises the patch formats it accepts in the `Accept-Patch` response header, e.g. `Accept-Patch: application/merge-patch+json, application/json-patch+json`. Clients rarely use it, but naming it demonstrates you have read RFC 5789 rather than absorbed folklore.