Accept-Patch

What is the Accept-Patch header?

The Accept-Patch response header, defined in Section 3.1 of RFC 5789 alongside the PATCH method, lists the patch document formats a resource accepts. Its value is a comma-separated list of media types, with optional parameters:

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

A PATCH body is not the new state of the resource, it is a set of instructions for changing it, and its media type decides how those instructions are read. The same JSON object means something different as a JSON Merge Patch (application/merge-patch+json, RFC 7396) than it does as a JSON Patch (application/json-patch+json, RFC 6902). Accept-Patch is how a client finds out which interpretations the server supports before it sends one.

RFC 5789 gives the header two meanings: the presence of Accept-Patch on a response to any method implies that PATCH is allowed on that resource, and each listed type is one the resource will accept.

API Usage & Best Practices

• Send it on OPTIONS for every patchable resource. RFC 5789 says it SHOULD appear in the OPTIONS response for any resource that supports PATCH, next to an Allow header listing PATCH.
• Send it on 415 responses. When a client sends a patch format you do not support, answer 415 Unsupported Media Type with Accept-Patch listing what you do support. RFC 5789 Section 2.2 says such a response SHOULD include it, and it turns a dead end into a one-step fix.
• Do not list application/json as a patch format. Plain JSON has no defined patch semantics, so a server that accepts it has invented its own, and a client cannot tell from the header which one. Accept application/merge-patch+json for simple field updates and application/json-patch+json when clients need array operations or tests, and say so explicitly.
• Only list a type on a resource that really takes it. Its presence is a promise that PATCH works. Do not emit a blanket Accept-Patch on read-only resources or on collections that only take POST.
• Keep it out of Accept. Accept is a request header about response formats. Accept-Patch is a response header about request formats. They answer different questions, and its sibling for POST is Accept-Post.
• Reject malformed patches with 400, unprocessable ones with 422. RFC 5789 distinguishes a badly formatted patch document (400 Bad Request) from a valid one that cannot be applied (422 Unprocessable Content), and a failed If-Match precondition from both (412 Precondition Failed). See PATCH strategies.

Examples

Discovering what a resource accepts before patching it:

OPTIONS /v1/users/42 HTTP/1.1
Host: api.example.com

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

A client sent plain JSON and was told which formats would have worked:

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/problem+json
Accept-Patch: application/merge-patch+json, application/json-patch+json

{
  "type": "https://apiguide.dev/errors/unsupported-media-type",
  "title": "Unsupported Media Type",
  "status": 415,
  "detail": "PATCH bodies must be application/merge-patch+json or application/json-patch+json."
}