通过REST API设置状态

Question

Is there a convention for exposing a state update function to the API consumer?

I have a /orders endpoint, where each order can have some states eg: 1 - Submitted 2 - Pending 3 - Shipped

Customers can submit orders, but then staff will eventually have their own GUI to change order state.

I'm wondering, for a particular order eg /orders/123 , would it be better to consume the API using PUT /orders/123 with {state: 2} .

Or would it be better to expose some convenience functions such as GET /orders/pending that would handle setting state for the API consumer?

Answer 1

The common practice is to use GET requests as read-only data access, and PUT requests to set state, updates, and other data write operations.

Aside from being common, this practice has the added benefit of being intuitive, and relays the intent of the API and client code that's accessing the API really well.

Note, however, that PUT verb is really meant to replace a resource in full, not for updating any single property of a resource. There's another HTTP verb for that - PATCH - which would be better suited for your case.

Rather than creating yet another copy of HTTP verbs reference, I'd like to refer you to this tutorial , which I found quite excellent and thorough. Take a look at both PUT and PATCH verbs to make a decision for your implementation.