using HTTP PUT, but not fully replace the entity

Question

Hi guys,

I'm developing a REST api, and I'm wondering the following:

I want to use HTTP PUT to update some entities in the webservice. The format will be a urlencoded body. Is it acceptable to only update the fields that were actually specified, rather than the entire entity?

I'm asking, because PUT would be a very convenient method to do some updates, but I don't want them to remove fields if they just happened to misspell some of them. Additionally, I don't want to force the implementor to always have to do a GET first and copy every single field they might not actually use..

Answer 1

I would say it may make sense. I consider the REST idea very flexible, so if you Update one entity why not only transfer the fields that need to be updated in your implementation. It is true, that it needs more server sided effort though. You have to check if the entity is available and can be updated with the data transferred and you need validation checks (as opposed to schema free document oriented data).

<!-- PUT books/1337 -->

<book>
    <title>Hello</title>
    <author>John Doe</author>
</book>

<!-- PUT books/1337 -->

<book>
    <title>Hello here I am</title>
</book>

Answer 2

Put is only for complete replacement. There is a proposal for the verb PATCH to address the problem you have (http://www.ietf.org/internet-drafts/draft-dusseault-http-patch-14.txt)

Patch, however, still may not be what you want. What is sent is an update resource that can do things like increment counters and so, unlike put, isn't idempotent.

You could expose each field as a resource and do multiple puts to each field. You can pipeline the puts to mitigate the extra latency.

Answer 3

You could simply POST the updated properties to the resource. Remember POST is the catch-all verb that you can use to do whatever you need to do when the other verbs don't work for you.

Check out Roy's article It's ok to use POST

Answer 4

I've never liked any of the solutions for partial updates, either. If I were designing a web service for widespread use, I'd probably go with POST. If it were for use by a fairly small number of people, i.e., I could talk to all the people I expected to call it, I've had two different ideas for addressing it.

1. PUT to a new 'update' resource. It would basically record the update you want to apply and then be in charge of not applying duplicates. I envision this working somewhat like a version control system that keeps a list of patches/changesets and gets pretty complicated every time I try to think out all the corner cases.

2. PUT to the resource, but don't change any fields that are not present. Require fields that you want to NULL out to be present with a special attribute indicating that you want to NULL it out. This seems far more practical, but doesn't fit in very well with the consensus that PUT should be a complete update.

If anyone has pointers to discussions of similar ideas, please edit/comment accordingly.