REST Partial Updates: Use POST, PUT or PATCH?

A couple of articles I have read recently are debating different options for partially updating a resource when you do not want to change or pass the whole thing.

Take, for example this use case for a The Knot Checklist checklist: a vast majority of the time, an update for is simply to “check” or “uncheck” an item, it is very rare that you would want to update the description, the due date, or any of the other meta data on the item. In fact, for checklist items that are pre-populated by editorial, you cannot change any of this information and the checklist api will ignore it if you try.

In an RPC-style API, you would simply create another method to handle this case, something like:

GET /rpc/checklist/setItemStatus?completed=true&itemId=1

But in a REST style API what do you do? If you used the normal update path, you would have to pass all the data:

PUT /checklist/item/1
{id: 1, name: "book a honeymoon", dueDate: ";3/18/2011", 
createdDate: "3/18/2011", editorialTaskId: 74, completed: true}

This wastes a lot of memory and bandwith constantly sending all of this information back and forth across the boundaries. So, According to the HTTP spec, you would use a verb named PATCH:

PATCH /checklist/item/1
{completed: true}

However not all web servers (and forget about clients) support PATCH so people have been supporting both partial updates with POST:

POST /checklist/item/1
{completed: true}

And partial updates with

PUT / checklist/item/1
{completed: true}

Since neither are correct, both are acceptable.

Using partial PUT would keep a more consistent mapping with how implementing REST as CRUD operations. On the other hand, if POSTing to a list means: adding a resource to that list, then POSTing to an item would indicate adding data for that item. Not exactly right, but I can see the argument.

Here are some additional articles on the subject:

And the apigee blog post that started me thinking about this:

Tagged REST architecture
Meta