Proper way to include data with an HTTP PATCH request

Question

When I\'m putting together an HTTP PATCH request, what are my options to include data outside of URL parameters?

Will any of the following work, and what\'s the most com

Answer 1

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 the Request-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 PATCHing:

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. The application/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.

Answer 2

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.

Answer 3

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 a PATCH request with a media type whose specification does not define semantics specific to PATCH, the server SHOULD reject the request by returning the 415 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 as application/xml or application/json. Doing so will cause interoperability issues, because the semantics of PATCH 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.