REST purists insist that PATCH is the only "correct" way to perform partial updates , but it hasn't reached "best-practice" status just yet, for a number of reasons.
Pragmatists, on the other hand, are concerned with building mobile back-ends and APIs that simply work and are easy to use, even if that means using PUT to perform partial updates .
The problems with using PATCH for partial updates are manifold:
- Support for PATCH in browsers, servers and web application frameworks is not universal. IE8, PHP, Tomcat, django, and lots of other software has missing or flaky support for it. So depending on your technology stack and users, it might not even be a valid option for you.
- Using the PATCH method correctly requires clients to submit a document describing the differences between the new and original documents, like a diff file, rather than a straightforward list of modified properties. This means the client has to do a lot of extra work - keep a copy of the original resource, compare it to the modified resource, create a "diff" between the two, compose some type of document showing the differences, and send it to the server. The server also has more work to apply the diff file.
- There's no specification that says how the changes in the diff file should be formatted or what it should contain, exactly. The RFC simply says:
"With PATCH, however, 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."One early recommendation for using PATCH is the JSON Patch RFC . Unfortunately, the spec overly complicates updating. I describe a much simpler alternative below, which works with either PATCH or PUT.
Pragmatic partial updates with PUTUsing PUT for partial updates is pretty simple, even if it doesn't conform strictly to the concept of Representational State Transfer. So a fair number of programmers happily use it to implement partial updates on back-end mobile API servers. It's fair to say that when developing an API, a pragmatic approach that focuses on the needs of mobile client applications is completely reasonable.
Current "best practices" when using PUT for partial updates, as I see it, is this: When you PUT the update:
- Include the properties to be updated, with their new values
- Don't include properties that are not to be updated
- Set properties to be 'deleted' to null
Update: This pragmatic approach to updates is used by a number of exemplary SaaS companies, including Github. It can also be used with the HTTP PATCH method, and it has now been formalized in RFC 7386 JSON Merge Patch .
Further reading1. http://williamdurand.fr/2014/02/14/please-do-not-patch-like-an-idiot/