Proper way to include data with an HTTP PATCH request
The PATCH
method is defined in the RFC 5789. This document, however, doesn't enforce any media type for the payload:
The
PATCH
method requests that a set of changes described in the request entity be applied to the resource identified by theRequest-URI
. The set of changes is represented in a format called a "patch document" identified by a media type.
Other RFCs, released years later, define some media types for describing a set of changes to the applied to a resource, suitable for PATCH
ing:
application/json-patch+json
Defined in the RFC 6902:
JSON Patch defines a JSON document structure for expressing a sequence of operations to apply to a JavaScript Object Notation (JSON) document; it is suitable for use with the HTTP
PATCH
method. Theapplication/json-patch+json
media type is used to identify such patch documents.
application/merge-patch+json
Defined in the RFC 7396:
This specification defines the JSON merge patch format and processing rules. The merge patch format is primarily intended for use with the HTTP
PATCH
method as a means of describing a set of modifications to a target resource's content.
There are no restrictions on the entity bodies of HTTP PATCH
requests as defined in RFC 5789. So in theory, your options in this area are unlimited.
In my opinion the only sensible choice is to use the same Content-Type
used to originally create the resource. The most common choice is application/json
simply because most modern APIs utilize JSON as their preferred data transfer format.
The only relevent statement RFC 5789 makes in regard to what should and shouldn't be part of your PATCH
entity body is silent on the matter of Content-Type
:
the enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version.
In summary, how you choose to modify resources in your application is entirely up to you.
As rdlowrey writes, RFC 5789 does not mandate specific content types, so the choice of format is up to you.
However, using the general formats you listed or making up your own format is not interoperable, and developers could have a hard time figuring out the semantics you chose. An official erratum to the RFC states this in a more formal way:
The means of applying a
PATCH
request to a resource's state is determined by the request's media type. If a server receives aPATCH
request with a media type whose specification does not define semantics specific toPATCH
, the server SHOULD reject the request by returning the415 Unsupported Media Type
status code, unless a more specific error status code takes priority.
In particular, servers SHOULD NOT assume
PATCH
semantics for generic media types that don't define them, such asapplication/xml
orapplication/json
. Doing so will cause interoperability issues, because the semantics ofPATCH
become specific to that resource, rather than general.
(Quote formatted for readability, but unchanged otherwise)
One media type whose specification defines PATCH semantics is application/json-patch+json
, also called JSON Patch: RFC 6902. I suppose it could be considered the "standard" choice (at least) when dealing with data originally posted as JSON.