REST APIs and predetermined sequence of states - rest

Question

I'm fairly new to REST APIs, and I have been puzzling over how to model a situation where you want to model a predetermined sequence of states in a REST API, such that you can only move forward through those states.
To give a toy example, consider a "steak" resource.
First you POST to /steaks to get a new steak. You get back a representation like the following.
{
"id": 4,
"cooking_state": "raw"
"next": "rare"
}
You want the user to be able to prompt transition to the next cooking_state in the sequence, until the steak the the desired level of cooked. So you might want them to be able to make some request that makes the resource at /steaks/4/ go through something like the following sequence (assume they like their steak well-done).
{
"id": 4,
"cooking_state": "blue"
"next": "rare"
}
{
"id": 4,
"cooking_state": "rare"
"next": "medium rare"
}
{
"id": 4,
"cooking_state": "medium rare"
"next": "medium"
}
{
"id": 4,
"cooking_state": "medium"
"next": "medium well"
}
{
"id": 4,
"cooking_state": "medium well"
"next": "well done"
}
{
"id": 4,
"cooking_state": "well done"
"next": null
}
(Let's say that eating the steak is modelled by a DELETE request.)
What you don't want to allow is jumping ahead or moving backwards.
{
"id": 4,
"cooking_state": "blue"
"next": "rare"
}
{
"id": 4,
"cooking_state": "well done"
"next": null
}
{
"id": 4,
"cooking_state": "medium rare"
"next": "medium"
}
None of the approaches I have thought of seem adequate, but I'll go through them.
PUT or PATCH request
A PUT or PATCH request seems ill-fitted to this sort of situation. Sure, you could start with...
{
"id": 4,
"cooking_state": "blue"
"next": "rare"
}
... and then PUT to /steaks/4/:
{
"id": 4,
"cooking_state": "rare"
"next": "medium rare"
}
Or maybe some sort of "merge patch":
PATCH /steaks/4/ HTTP/1.1
{
"cooking_state": "rare"
}
Then if someone tries to update the cooking state out of sequence, you could forbid it (409 status code?). But putting or patching seems to imply a level of freedom that doesn't exist.
Verbs, possibly thinly disguised
In some ways it feels more natural to me to move between states with a bodyless post request. Something like one of the following:
POST /steak/4/?action=next
POST /steak/4/cooking_state?action=next
But that feels very "verb-ish". It feels like a thin veneer over:
POST /steak/4/fry/
POST-ing events
You could POST cooking "events".
First, you create your steak...
POST /steaks/
... and get back the following response body.
{
"id": 5,
"cooking_state": "raw",
"next": "blue"
}
You can then query /steaks/5.
Then to cook the steak by one stage you make a request like the following:
POST /cooking_event/
{
"steak_id": 5
}
After this, a previously raw steak at /steaks/5/ would now look like this:
GET /steaks/5/
{
"state": "blue",
"next": "rare"
}
You make an identical POST request again, and now steak 5 looks like:
GET /steaks/5/
{
"state": "rare",
"next": "medium rare"
}
But, since the database row probably looks like this...
id cooking_state
5 "rare"
... there probably wouldn't be any actual event resource created, so you wouldn't be able to query GET /cooking/events/<id>/ - another thing which I'm not sure is acceptable or not in RESTful terms.
Again, this feels like a (this time more complex) veneer over verbs. It's like saying "The event which is the cooking of the steak" when you mean "Please cook the steak".
Obviously, the steak example may seem silly, but there are situations where it would be important to allow certain fields to be updated only in particular sequences. Is there an elegent way of dealing with this which is still fully RESTful?

Answer 1

Your example is a bit unsuited for your problem, because you don't actually set the state of the steak, you check it and try to decide if that's what you want. Basically you would do polling with a bunch of GET.
To be more practical (which oddly enough in this case means more abstract), suppose you have wizard-like kind of form that you want the user to fill.
You POST the form, and the result contains two main values:
the validation result (are the values ok AND is the user in the correct step?)
the path for the next step (what should the user do now?). If there is no next step, the user is done. If there is a next step, the user POSTs to that step and get the same kind of result.
If the user tries to go to the next step without having visited the previous ones, you return an out of sequence kind of error, which in your case I'd say is 412 Precondition failed .

Answer 2

Your example demonstrates the difficulty of modelling a ReSTful API well. Not because of problems with ReST itself, but because of domain complexity. However, I don't think the example really works. Either of your solutions may be appropriate in certain situations. It all depends on how you analyse the domain.
One analysis may suggest that if a steak is being cooked then its 'state' is not really a function of what your 'client' (diner?) does to it at all, it's a function of time and temperature. So your state change problem is really something which the client has no control over at all. In this model, the client would poll the resource until the 'state' changed (as if by magic) to the desired one and then 'consume' it (by calling DELETE). Any 'update' privileges which the client has would preclude them changing the 'state' field. The states are then managed by the server somehow. In essence, your API server is acting as a grill - the client creates an item to be 'cooked' and the server then cooks it until the client consumes it.
Another analysis may say that you've got two types of client - a 'diner' and a 'cooker'. When a diner requests a steak (POST to /steaks) a new resource is created to which they have no 'update' (PUT) privileges. A more privileged 'cooker' client may then periodically update the state of the resource whereas the diner client only has privileges to GET or DELETE it. In that model, it's the responsibility of the 'cooker' to enforce your state model and the API server itself doesn't enforce it. The API server isn't really anything more than a glorified order system - the cooker may for example decide to restart the state machine (because it dropped the steak). Either way the responsibility resides in one place, and the API would work with a PUT model because the the cooker client would simply be updating the resource.
Yet another interpretation says that the API server has to enforce the state machine even though there are the two types of client. In this case, the 'event' model really is appropriate. The 'cooker' only knows what's happened (i.e. what events have occurred) and the API server is responsible for maintaining the state transitions. Again, it's all hidden from the 'diner' client anyway. They just get to DELETE the steak when appropriate. This model can be very much more appropriate if you've got an API server which coordinates events from multiple sources (hey, you want mushrooms with your steak, right?).
Your concern about POST-ing events to a resource which doesn't end up creating a resource you can GET from is valid but there are always exceptions. For those it's perfectly acceptable to return a 204 (No Content) or (202 Accepted) without returning a Location you can get anything from. In the real world, if you did have a state model being influenced by a stream of events then you probably would want to keep a record of the incoming events in some kind of data store, and so you could potentially layer a resource over that (if appropriate).
YetAnoterInterpretation might suggest that there's only 1 client, with total control over any state transitions. That could be totally acceptable too - maybe I actually cook my own steaks and I just need a record of what I've done...
Ultimately, it's all down to where responsibility lies and how your individual use case is modelled. One thing does seem certain about your example - there should be only one place which is responsible for enforcing the state transitions. Exactly where the responsibility lies, and how to model it ReSTfully, is another question.
Moving on from the steak example, if you find that you've got resources which have a subset of fields on them which are updated according to some kind of state machine, independently of other resource fields, then you might want to model that as a kind of sub-resource, and then working out who is actually in control of that part of the resource (i.e. who actually enforces the state transitions) and break responsibilities down accordingly.