When Is POSTing State Appropriate?

In an article, Tim Bray, examines the feedback from the first public draft of the APIs for the Sun Cloud. He responds to feedback in the article and explores the ways to model interactions such as, creating a VM in a Cluster, in a RESTful way.

He presents a few scenarios in the context of the design of Sun’s cloud API’s and asks if POSTing state to model such interactions is an appropriate strategy.

But you’re not really changing a state, you’re requesting a specific set of actions to happen, as a result of which the state may or may not attain the desired value. In fact, when you hit the deploy switch, the state changes to deploying and then after some unpredictable amount of time to deployed. And the reboot operation is the classic case of a box with a big red switch on the side; the problem is how to push the switch.

So, the more I think of it, the more I think that these resources are like buttons, with only one defined operation: push. People have been whining about “write-only resources” but I don’t have a problem with that because it seems accurate. The reboot and halt buttons don’t really have any state, so you shouldn’t expect anything useful from a GET.

Bill de hÓra in reaction to the article provided, with examples, the distinction between PUT and POST and when one is more appropriate vs. the other.

When does PUT v POST actually *matter*? It matters, as far as I can tell, when your resource stands for a collection, which is very common - folders, albums, feeds, collections, blogs, tagclouds, orders, a shopping cart - any list based structure.

He also presents a more pragmatic aspect of the whole debate and suggests POSTing forms as a possible solution.

On the other hand lots and lots and lots of people don't, won't (and sometimes can't) care about REST/HTTP/AtomPub arcana. So some part of me thinks we need patterns and practices to help developers jfdi [just do it].

But as far it goes as I'm not sure we in the pro-REST community have a good general answer or design pattern for partially updating a resource. Until we do, I predict people will tend drop down to using forms posting as it's the easiest and most portable approach for deployed client libraries and web frameworks. That or define some other specialised media type for partial updates.

Roy Fielding  responded to the article as well.

The main reason for my lack of specificity [in my thesis] is because the methods defined by HTTP are part of the Web’s architecture definition, not the REST architectural style. Specific method definitions […] simply don’t matter to the REST architectural style, so it is difficult to have a style discussion about them. The only thing REST requires of methods is that they be uniformly defined for all resources (i.e., so that intermediaries don’t have to know the resource type in order to understand the meaning of the request).

POST only becomes an issue when it is used in a situation for which some other method is ideally suited. The other methods are more valuable to intermediaries because they say something about how failures can be automatically handled and how intermediate caches can optimize their behavior. POST does not have those characteristics, but that doesn’t mean we can live without it. POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.”

Roy concludes his response saying

We don’t need to use PUT for every state change in HTTP. REST has never said that we should. […] Personally, I would just use POST for that button. The API can compensate for the use of POST by responding with the statement that the client should refresh its representation of the larger resource state. In other words, I would return a 303 response that redirected back to the VM status, so that the client would know that the state has changed.

The original article is available here with reactions from the community.