23

Sam Ruby, author of "RESTful Web Services" seems to come out against the use of HTTP PUT for partial updates: http://intertwingly.net/blog/2008/02/15/Embrace-Extend-then-Innovate

What isn't clear is how partial updates should take place. As I commented near the bottom of his blog, it isn't clear how using HTTP PATCH is any better than using a "patch document" against HTTP PUT.

It is worth noting that although Sam comes out against misusing HTTP PUT he doesn't seem to advocate the use of HTTP PATCH either.

How should one submit RESTful partial updates?

Gili
  • 86,244
  • 97
  • 390
  • 689

4 Answers4

21

As you can see from the comments in the blog post you referenced there is no agreed upon way to do partial updates. If heavyweights like Sam Ruby, Joe Gregario, Mark Nottingham, Mark Pilgrim, Bill de hÓra, etc cannot come to an agreement, what hope do we have.

As far as I am concerned, I wouldn't worry too much. Create a partial update media type that works for you, use PATCH to indicate your intent and when agreement is finally reached on a general purpose media type, change your server to accept both formats.

Be thankful that if the worst sin your REST api commits is abusing PUT/PATCH then you are doing pretty well.

Vihung
  • 12,947
  • 16
  • 64
  • 90
Darrel Miller
  • 139,164
  • 32
  • 194
  • 243
16

It is now year 2013 - you should use PATCH for partial updates - either using json-patch (see https://www.rfc-editor.org/rfc/rfc6902 or http://www.mnot.net/blog/2012/09/05/patch) or the xml-patch documents (see https://www.rfc-editor.org/rfc/rfc7351). In my opinion though, json-patch is the best fit for your kind of business data.

PATCH with JSON/XML patch documents has very strait forward semantics for partial updates. If you start using POST, with modified copies of the original document, for partial updates you soon run into problems where you want missing values (or, rather, null values) to represent either "ignore this property" or "set this property to the empty value" - and that leads down a rabbit hole of hacked solutions that in the end will result in your own kind of patch format.

You can find a more in-depth answer here: http://soabits.blogspot.dk/2013/01/http-put-patch-or-post-partial-updates.html.

Update: Is this RPC?

Well, if you define RPC as sending commands to a server then any and all HTTP operations are RPC calls - whether you GET a resource, PUT a new representation or DELETE it again - each of them consist of a sending a command (verb) GET/PUT/DELETE etc. and a optional payload. It just happens that the HTTP working group (or who ever it is) has introduced a new verb PATCH which allows clients to do partial updates to a resource.

If anything else than sending the complete representation to the server is considered RPC style, then, by definition, partial updates cannot be RESTful. One can choose to have this point of view, but the people behind the web infrastructure says differently - and has thus defined a new verb for this purpose.

RPC is more about tunnelling method calls through HTTP in a way that is invisible to intermediaries on the web - for instance using SOAP to wrap method names and parameters. These operations are "invisible" since there are no standards defining the methods and parameters inside the payload.

Compare this to PATCH with the media type application/json-patch - the intention of the operation is clearly visible to any intermediary on the web since the verb PATCH has a well defined meaning and the payload is encoded in another well defined public available format owned by common authority on the web (IETF). The net result is full visibility for everybody and no application specific secret semantics.

REST is also about "serendipitous reuse" which is exactly what PATCH with application/json-patch is - reusing an existing standard instead of inventing application specific protocols that do more or less the same.

Community
  • 1
  • 1
Jørn Wildt
  • 4,274
  • 1
  • 21
  • 31
  • I just read http://soabits.blogspot.dk/2013/01/http-put-patch-or-post-partial-updates.html and it smells like RPC to me. We're sending commands (e.g. add this, replace that) instead of resource representation. This might fit well in a SOAP world, but does not fit REST in my opinion. – Gili Jan 02 '13 at 23:41
  • I have updated my answer to cover this - it required quite a few more characters than is allowed in a comment. – Jørn Wildt Jan 03 '13 at 07:58
  • For all **practical** purposes a PATCH is virtually identical to a POST. Proxies will treat `PATCH` the same as `POST` (no caching of the resulting state). No proxy is going to bother implementing all `PATCH` variants. The only practical advantage might be client-side and server-side libraries for automatically creating/unpacking a patch. Was this really a problem worth solving in the first place? Questionable. I don't think I could have come up with a better solution. I'm just saying defining `PATCH` doesn't really add much value to what was already out there. – Gili Jan 03 '13 at 16:03
  • By the way, SPDY (aka HTTP 2.0) aims to do away with proxies (the transport layer is encrypted, including the headers) so this point might be moot. HTTP PATCH will be far more useful in this context (since there will be client-side and server-side libraries for each PATCH variant). – Gili Jan 03 '13 at 16:08
4

Instead of home-brewing a partial update media type and using the yet-non-standard PATCH method, you could give parts of your resources their own URI.

merwok
  • 6,779
  • 1
  • 28
  • 42
2

HTTP PATCH now has an RFC - HTTP PATCH RFC

Community
  • 1
  • 1
blank
  • 17,852
  • 20
  • 105
  • 159