How to submit RESTful partial updates?

Question

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?

Answer 1

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.

Answer 2

It is now year 2013 - you should use PATCH for partial updates - either using json-patch (see http://tools.ietf.org/html/rfc6902 or http://www.mnot.net/blog/2012/09/05/patch) or the xml-patch documents (see http://tools.ietf.org/html/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.

Answer 3

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.

Answer 4

HTTP PATCH now has an RFC - HTTP PATCH RFC