14

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 common choice?

  • multipart/form-data
  • application/x-www-form-urlencoded
  • Raw JSON
  • ...any others?

3 Answers 3

8

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.

3
  • 2
    Nope. The media type is supposed to describe the patch format. If you sue a media type which lacks a definition for use in PATCH, you aren't using PATCH the way it's supposed to be used. Commented Jun 9, 2015 at 21:08
  • 3
    @JulianReschke feel free to do something productive and post an RFC reference for your statement so people can benefit. Otherwise you aren't helping anyone. In particular, if this answer is wrong you should post a correct one.
    – user895378
    Commented Jun 11, 2015 at 4:26
  • 1
    Patch is strange. They published its rfc explicitly absent of any standard media types, assuming people would read between the lines and create their own. Two years later Mark Nottingham adds the errata as a result of people not creating patch-specific media types, crying 'interoperability!', and one year after that the json patch rfc is published. If interoperability was such a concern, shouldn't they have published at least one patch-specific media type alongside publishing the patch rfc?
    – aaaaaa
    Commented Jun 2, 2016 at 5:53
4

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.

3

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.

1
  • The trouble with both Json Patch and Merge Patch is that they both require the original resource to be unmodified since it was last fetched by the client, otherwise operations on array elements may be performed on the wrong element. So if you are thinking that PATCH (largely) solves the problem of concurrent updates you are mistaken - you still need a mechanism such as ETag/If-Match.
    – Ian Goldby
    Commented Sep 15, 2021 at 7:45

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.