5

I wonder, what would the more RESTFul, flexible and better approach of updating(!) a field (state) of an item

/api/v1/items/:id?action=start 
/api/v1/items/:id/start 
/api/v1/items/:id/ + action in the body
/api/v1/items/:id/status/{active|stopped}

or items

/api/v1/items?action=start 
/api/v1/items/start 
/api/v1/items/ + action in the body
/api/v1/items/status/{active|stopped}

3 Answers3

6

I would prefer the third API structure:

/api/v1/items/:id/ + action in the body

My reasons include:

  • According to the Richardson Maturity Model the URL should point to a specific resource or set of resources. You do not want to add update information within the URL, as it doesn't qualify as a valid endpoint.
  • You want to use PUT for update/replacement operations which affect a resource. Let the URL select the resource and let the body define the exact fields you want to update, and any other logic otherwise.
  • Using the body rather than the query string allows you to insert arbitrarily large information (to a certain limit, but greater than a query string) which logically might be paired with the operation (start in your case). It allows greater flexibility in extending the operation in the future as well.
  • You can probably list the relevant actions that can be performed on the endpoint inside the response of /api/v1/items. This would be a list of informative hypermedia controls. Again, the Richardson maturity model provides a very good example.
Colin 't Hart
  • 7,372
  • 3
  • 28
  • 51
Nikhil
  • 2,298
  • 13
  • 14
2

As alternative you can implement the PATCH method. It would provide you with the possibility to update selective fields. The only problem with PATCH is thats its unknown because the RFC is young. The actual implemention depends on your server and client side libraries and frameworks.

When you dont want to use PATCH the only alternative is to implement overriden POST and define the update mechanism. For example, you can say: Every field != null will override the resource field value.

Orri
  • 920
  • 1
  • 8
  • 20
0

Lets re phrase the question: how do i change few attribute of my resource. (status is just another attribute)

Answer:

identify a resource.

Use POST (since the request is non idempotent) supply in body, since in future you may need to change more attribute than just status for this resource.

POST /api/v1/items/:id + action in the body

use only POST method.

Reason: Put should be used when it changes the complete set of properties not one or partial property(ies).

Please, let’s move on. We don’t need to use PUT for every state change in HTTP. REST has never said that we should. It is okay to use POST - roy t fielding

Community
  • 1
  • 1
rawjean
  • 51
  • 4
  • 1
    The HEAD method is identical to GET except that the server MUST NOT return a message-body in the response. HEAD is far away from being used for updating leave alone for updating resulting in a non idempotent state. – rawjean Oct 01 '13 at 14:16
  • but put should be used for creating. –  Oct 01 '13 at 14:45
  • 1
    POST should be using for creating, PUT for updating. Return `201 Created` if the PUT was for an object that didn't yet exist and `200 OK` if the update went OK. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.6 – Colin 't Hart Oct 01 '13 at 16:39
  • 1
    What's your source of "Put should be used when it changes the complete set of properties not one or partial property(ies)"? I don't read this in the HTTP specification at all. – Colin 't Hart Oct 01 '13 at 16:45
  • Oh, and please merge this answer into the original question! – Colin 't Hart Oct 01 '13 at 16:47
  • POST should be used strictly for creation. A partial update can be interpreted as a full replacement of an object, hence PUT is a better choice. Also it gives better clarity and separation of concerns. Mixing an update action with a creation verb is just confusing. – Nikhil Oct 01 '13 at 17:51
  • PUT is a better choice. Note that updating a field of a resource is an idempotent action. POST is non-idempotent. – keya Apr 06 '17 at 10:40