Craig McClanahan, from Sun Microsystems, provided answers as to why existing "REST" APIs don't really take advantage of using Hypermedia as the Engine of Application State (HATEOAS) in RESTful services. He cites examples from his recent work in designing the Sun Cloud API to illustrate the benefits.
We started from the presumption that the service would publish only one well-known URI (returning a cloud representation containing representations for, and/or URI links to representations for, all the cloud resources that are accessible to the calling user). Every other URI in the entire system (including all those that do state changes) are discovered by examining these representations.
Craig suggests having the hypermedia guide clients through the resource graph; just as an interactive web application would a user, by representing the resources and their relationships as hypermedia with links that connect them; allowing clients to navigate the resource representations effectively and drive application state. In his opinion, the benefits of such a design are:
- REDUCED CLIENT CODING ERRORS. [A]bout 90% of the bugs have been in the construction of the right URIs for the server. Typical mistakes are leaving out path segments, getting them in the wrong order, or forgetting to URL encode things.
- REDUCED INVALID STATE TRANSITION CALLS. […] As an example [from the Cloud API …] it's not allowed to "start" a virtual machine (VM) until you have "deployed" it. The server knows about URIs to initiate each of the state changes (via a POST), but the representation of the VM lists only the URIs for state transitions that are valid from the current state.
- FINE GRAINED EVOLUTION WITHOUT (NECESSARILY) BREAKING OLD CLIENTS. At any given time, the client of any REST API is going to be programmed with some assumptions about what the system can do. But, if you document a restriction to "pay attention to only those aspects of the representation that you know about", plus a server side discipline to add things later that don't disrupt previous behavior, you can evolve APIs fairly quickly without breaking all clients, or having to support multiple versions of the API simultaneously on your server.
Marc Hadley, in his post, adds to the discussion, the idea that WADL can used to describe …
… a set of URIs and URI templates and relying on the client to construct URIs to access the resource they need, the cloud APIs only publish a single "root" URI and then document where to find additional URIs in representations that clients can use to traverse the service.
He describes how one might document a web application like the Sun Cloud API using WADL and goes on to illustrate his idea with an example.
- Use resource types to describe each kind of resource,
- Parameterize representations to identify links embedded within them,
- Define the types of resource each embedded link identifies.
Do check original post, and the discussions available in the rest-discuss group.