Accept-Patch general response

What it does

Accept-Patch advertises which media types a resource is willing to accept in the body of a PATCH request. Unlike PUT (which replaces an entire resource) or standard POST, PATCH applies a partial modification — but "partial modification" can be expressed in several genuinely different document formats (JSON Patch, JSON Merge Patch, XML Patch, and others), and there's no single universal default. Accept-Patch lets a server explicitly tell clients which of these formats it actually understands, rather than clients guessing or servers just returning a 415 Unsupported Media Type error after the fact.

Syntax

Accept-Patch: <media-type>
Accept-Patch: <media-type1>, <media-type2>

Example:

Accept-Patch: application/json-patch+json, application/merge-patch+json

Typically appears on OPTIONS responses (as part of resource capability discovery) but can also be included on any response where it's relevant.

Common PATCH document formats

JSON Patch and JSON Merge Patch solve overlapping but genuinely different problems: JSON Patch supports precise, ordered operations (including array manipulation like moving an element), while Merge Patch is simpler — you send a partial object, and its fields get merged into (and can null out fields of) the target resource, but it can't express operations like "remove an array element by index" as cleanly.

How it's used in practice

• API capability discovery via OPTIONS — a client can send OPTIONS to a resource and check the returned Accept-Patch header to learn which patch format(s) that specific endpoint supports before attempting an actual PATCH request.
• APIs supporting multiple patch formats simultaneously — some APIs advertise support for both JSON Patch and JSON Merge Patch, letting clients choose whichever fits their use case (Merge Patch for simple field updates, JSON Patch for precise array/ordering operations).
• Avoiding trial-and-error PATCH requests. Without Accept-Patch, a client has no reliable way to know what format a PATCH endpoint expects short of documentation or guessing — this header makes that discoverable at the protocol level.

Common mistakes and gotchas

Implementing PATCH without advertising Accept-Patch at all. A PATCH endpoint that accepts a specific format but never communicates which one leaves clients to figure it out through documentation or trial and error — advertising via Accept-Patch (especially on OPTIONS responses) is considered a best practice for discoverable API design.

Confusing JSON Patch and JSON Merge Patch semantics. These formats aren't interchangeable — sending a JSON Merge Patch document to an endpoint expecting JSON Patch operations (or vice versa) will either fail outright or, worse, be silently misinterpreted in a way that doesn't do what the client intended. Always match the Content-Type of your actual PATCH request body to a format the server's Accept-Patch actually lists.

Assuming null handling is the same across formats. JSON Merge Patch has specific, spec-defined semantics for null values (setting a field to null removes it from the target resource) — this is a common surprise for developers used to null simply meaning "no value" in other contexts, and it's worth understanding explicitly before using Merge Patch for partial updates.

Not validating patch documents before applying them. Especially with JSON Patch's operation-based format, a malformed or logically inconsistent set of operations (like a test operation that fails, or a move referencing a nonexistent path) needs proper server-side validation and error handling — blindly applying whatever operations arrive can lead to unexpected resource states.

Real-world examples

Discovering supported patch formats via OPTIONS:

OPTIONS /api/users/42 HTTP/1.1

HTTP/1.1 204 No Content
Accept-Patch: application/json-patch+json, application/merge-patch+json
Allow: GET, PATCH, DELETE

A JSON Patch request against an endpoint that advertised support for it:

PATCH /api/users/42 HTTP/1.1
Content-Type: application/json-patch+json

[
  {"op": "replace", "path": "/email", "value": "[email protected]"},
  {"op": "remove", "path": "/nickname"}
]

A JSON Merge Patch request:

PATCH /api/users/42 HTTP/1.1
Content-Type: application/merge-patch+json

{"email": "[email protected]", "nickname": null}

FAQ

What's the difference between JSON Patch and JSON Merge Patch?

JSON Patch (RFC 6902) is an explicit list of operations (add, remove, replace, move, copy, test) applied in order, giving precise control including array manipulation. JSON Merge Patch (RFC 7396) is simpler — you send a partial object that gets merged into the resource, with null values removing fields, but it can't express certain operations (like array element reordering) as cleanly as JSON Patch can.

Do I need Accept-Patch if my API only supports one patch format?

It's still good practice — even with only one supported format, advertising it explicitly (especially via OPTIONS) makes your API more discoverable and self-documenting, rather than requiring clients to consult separate documentation to learn what to send.

What happens if I send a PATCH request in a format the server doesn't support?

The server should respond 415 Unsupported Media Type, ideally including Accept-Patch in that error response so the client can see what formats are actually supported and retry correctly.

Is Accept-Patch only relevant to OPTIONS responses?

It's most commonly seen on OPTIONS responses as part of capability discovery, but it can technically appear on other responses too — the header itself isn't restricted to any single method's response, though OPTIONS is the conventional place clients look for it.

Fun fact

JSON Patch and JSON Merge Patch were standardized as separate, complementary RFCs (6902 and 7396) rather than one API author picking a single "correct" partial-update format — this reflects a genuine, unresolved design tension in API design: precise operation-based patching versus simple object-merge patching each have real strengths for different use cases, and rather than the IETF picking a winner, both became standards, leaving Accept-Patch as the mechanism for servers to communicate which one (or both) they've chosen to support.