One of the understandings of REST that seems to be overlooked the most is its ability of guiding a consumer of a service through the various transitions using hyper-media.
To simplify what this means, imagine you start at the base URI for a service that allows you to place an order. To place an order, you PUT or POST a representation of an order to a URI provided in the initial representation. You do not know what this URI is until you GET the starting representation from the base URI of the service, which contains links to resources (URI’s) that you can interact with from this starting state.
So you have your order representation, and you’ve got the URI to send it to, so off you go and POST. The order is placed and a representation is returned to you that contains the order you placed, and more interestingly, more URI’s that may enable you to cancel, modify or confirm the order. This is now the second state of the order placement process of the service, which you have been guided to through hyper-media links.
The key here is that all you know is you want to place an order, perhaps modify it, and eventually confirm it. Where you POST/PUT/GET representations to, i.e the URI’s, shouldn’t be something the client has hard-coded in their client API. The service will guide you through the state of the application through links.
So, by giving the client the initial start URI of the service, that client should be able to walk over the entire landscape of URI’s in the service landscape, entirely guided through hyper-media links.
The biggest advantage to this is that the service is in complete control of its addressing. If for some reason the work flow changes slightly, for example, more states are introduced to the order placement process such as promotions, and new URI’s are created or changed, the client will not break as it is not tightly coupled to the addressing of the service.
However, one important thing to note here is that the client is still dependant on 2 things.
The first being how the links are represented in the representations. The links will be described semantically, perhaps through a <link> element or in the example above, an XHTML tag <a rel=”placeOrder”> for the place order process. The SLA between the client and the service must be that these semantics are never changed.
Secondly, the process flow of the service. The service above allows me to successfully place an order in two state transitions. I first create my order, then I can confirm the order. If the service introduces a 3rd state between the 1st and 2nd, that will break the way my client interacts. However, if more URI’s are introduced in the 1st or 2nd state, for example, the service now supports adding promotion codes to the order before confirming, then the client will not break as it will simply ignore the URI’s it does not understand. This is powerful. The server has a lot more agility by introducing new state transitions in to current representations without breaking clients. Furthermore, the clients will not break if the service decides to change its URI format or structure! Lovely =)
Part of what I touched on this post is the SLA between RESTful services and clients. I am seeing a lot of confusion about how RESTful services are described to clients in the absence of the WSDL. Since this post is already a bit to take in, I will leave this until next time.