JSON Patch

JSON Patch is a JSON array of operations — add, remove, replace, move, copy and test — each naming a location in the target document with a JSON Pointer such as /tags/0. Sent as the body of a PATCH request with Content-Type application/json-patch+json, it tells the server exactly what to change rather than sending a new copy of the whole resource.

How it works

Operations apply in order, and the patch is meant to be atomic: if any operation fails, none of them should take effect. The test operation is a built-in precondition — "only apply this patch if /status is still draft" — which makes JSON Patch a lightweight form of optimistic concurrency at the field level.

The misconception

That a partial JSON object sent with PATCH is JSON Patch. That is JSON Merge Patch (RFC 7396), a different format where null means "delete this field" and arrays can only be replaced whole. Servers usually accept one or the other, and the Content-Type is how they tell them apart.

Try it here

PATCH /protocol/v1/documents/{id} takes an RFC 6902 array: add, replace, remove and test on /title, /body and /tags — a failing test answers 409, and a body that is not an array answers 400.

Related

• PUT vs PATCH
• HTTP 409 Conflict

Other terms

• Mock API — A stand-in for a real API that returns realistic responses without the real system behind it.
• REST API — An API that models a system as addressable resources, manipulated with standard HTTP methods.
• ETag — An opaque version identifier for a representation, used to avoid re-sending it and to detect conflicting writes.
• HATEOAS — Hypermedia as the Engine of Application State — responses carry the links to whatever you can do next.
• Bearer token — A credential where possession alone grants access — whoever holds it can use it.
• JWT (JSON Web Token) — A signed, self-contained token whose payload the server can verify without a database lookup.

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

Last updated 2 October 2026