Jay G.’s weblog

How to GET a Cup of Coffee

Last October, Jim, Savas, and Ian published a great article, “How to GET a Cup of Coffee“. In that article, the authors illustrated, through the example of Starbucks, how to develop enterprise workflows in RESTful way. They gave ideas of how we can use response codes for coordination, ETags for consistency, and caching for scalability and resiliency.

However, I have a few points I’d like to make.

1. Resource states and application states need to be explained separately.

   GET and HEAD are special cases since they don’t cause state transitions.

   As the above quote says, GET and HEAD don’t change any resource states. But they do cause application state transition. Think about Web browsers. When you click a link on the page, the Web browser will GET a representation of the resource pointed by the URI and move from one state to another. That’s exactly how you can see this page on your Web browser.

2. Everything you need to know is media type.

   <next/> tag in the article is primarily about hypermedia. The authors said the XML dialect used by Starbucks can embed information about another resource. However, IMHO, the only information that need to be embedded in that dialect is the identifier of the resource, such as URL.

   Here is where “Hypertext As The Engine Of Application State” comes into play. The next state has to be described by only a representation of the resource. A single resource can have multiple representations in different media types, each media type defines its own processing model, and every resource representation can be described by themselves (i.e., self-describing resource representations).

   So I don’t know why we need another namespace or a sort of standard for abstract state transitions. State transition is one of the basic notions of REST. Even if we have that namespace (like http://example.org/state-machine), we still need to define semantics of each type of transition in another namespace (like http://starbucks.example.org/payment). Furthermore, as long as the representation is self-described, we don’t need to set the rel attribute to the type of the representation in advance, because it can be derived by negotiation with the server. So, like the below, we can define a tag for a specific type of transition and its semantics can be defined by the tag itself. Then, we can re-use or standardize the namespace which defines that tag.

   <order xmlns="http://starbucks.example.org/">
     <drink>latte</drink>
     <additions>shot</additions>
     <cost>4.00</cost>
     <payment>https://starbucks.example.com/payment/order/1234</payment>
   </order>

3. The human Web is also RESTful.

   The consumer application - the Web browser - simply renders the HTML, and the state machine (that’s you!) follows links using GET and POST. In Web-based integration the same occurs, except the services and their consumers not only have to agree on the interaction protocols, but also on the format and semantics of the representations.

   I guess the above quote is in sort of contradiction to the following.

   In the human Web, consumers and services use HTML as a representation format. HTML has its own particular semantics, which are understood and adopted by all browsers.

   IMHO, in the human Web, the same occurs without any exceptions.

4. Some other comments…

   • I also think the use of PUT for partial updates is not a good idea. POST or PATCH seems a better option.
   • I wonder if using OPTIONS or Expect/Continue is always of benefit.
   • “URIs represent the transitions within a state machine.” is too simple and not accurate.
   • I think even if the resource is editable, there should be only one address for that resource.
   • We don’t need to use Microformats in XML. What about RDF?
   • I totally agree with the authors’ opinion about URI templates.
   • We have to understand the importance of evolution and partial understanding on the Web.

I guess the authors know very well everything that I mentioned above, but some newbies like me could be misled in some way. Anyway, this article is excellent and worth taking time to read.