Best practice for partial updates in a RESTful service

 

I am writing a RESTful service for a customer management system and I am trying to find the best practice for updating records partially. For example, I want the caller to be able to read the full record with a GET request. But for updating it only certain operations on the record are allowed, like change the status from ENABLED to DISABLED. (I have more complex scenarios than this)

I don't want the caller to submit the entire record with just the updated field for security reasons (it also feels like overkill).

Is there a recommended way of constructing the URIs? When reading the REST books RPC style calls seem to be frowned upon.

If the following call returns the full customer record for the customer with the id 123 

GET /customer/123
<customer>
    {lots of attributes}
    <status>ENABLED</status>
    {even more attributes}
</customer>

how should I update the status? 

POST /customer/123/status
<status>DISABLED</status>

POST /customer/123/changeStatus
DISABLED

...

Update : To augment the question. How does one incorporate 'business logic calls' into a REST api? Is there an agreed way of doing this? Not all of the methods are CRUD by nature. Some are more complex, like 'sendEmailToCustomer(123)', 'mergeCustomers(123, 456)', 'countCustomers()' 

POST /customer/123?cmd=sendEmail

POST /cmd/sendEmail?customerId=123

GET /customer/count

Thanks Frank

You basically have two options:

  • Use PATCH (but note that you have to define your own media type that specifies what will happen exactly)

  • Use POST to a sub resource and return 303 See Other with the Location header pointing to the main resource. The intention of the 303 is to tell the client: "I have performed your POST and the effect was that some other resource was updated. See Location header for which resource that was." POST/303 is intended for iterative additions to a resources to build up the state of some main resource and it is a perfect fit for partial updates.

    • You should use POST for partial updates.

    To update fields for customer 123, make a POST to /customer/123.

    If you want to update just the status, you could also PUT to /customer/123/status.

    Generally, GET requests should not have any side effects, and PUT is for writing/replacing the entire resource.

    This follows directly from HTTP, as seen here: http://en.wikipedia.org/wiki/HTTP_PUT#Request_methods

    You should use PATCH for partial updates - either using json-patch documents (see http://tools.ietf.org/html/draft-ietf-appsawg-json-patch-08 or http://www.mnot.net/blog/2012/09/05/patch) or the XML patch framework (see http://tools.ietf.org/html/rfc5261). 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.

    链接地址: http://www.djcxy.com/p/7920.html

    上一篇: 认证呼叫的REST设计

    下一篇: RESTful服务中部分更新的最佳做法