Review

This is both a manifesto for what the authors term ‘REST-Oriented Architecture’ (ROA), and a technical dive into the mechanics and semantics of REST. It comes as a big breath of fresh air after years of being harangued by the putative benefits of Service-Oriented Architecture (SOA) with its plethora of web-service standards centered on XML, SOAP, and WSDL, and the many competing and largely incompatible SOA toolkits.

REST (or ReST) stands for ‘Representational State Transfer’, a term and concept introduced by Roy Fielding nearly a decade ago. The basic idea is that, in current practice, the www consists in large part of interconnected resources where the connections are implemented by the basic HTTP methods of GET and POST, and resource representation is typically HTML, heavily annotated and marked-up, and difficult to work with programmatically. But HTTP, combined with suitably chosen URIs, and combined with more program-oriented representations such as XML and JSON, can provide us the combined advantages of the interconnected web and programmable ‘services’.

In the ReST model the HTTP methods (GET, PUT, POST, DELETE, and maybe HEAD) are the only methods that would be exposed by a web ‘service’. The service exposes URI (universal resource identifiers) for each of the resources provided by the service (a possibly unbounded set of resources), and the methods are applied to those URIs. Each resource can have one or many representations - for example, as XML, JSON, HTML, PDF, etc. There are multiple ways of selecting a representation: for example, adding an ‘Accept’ header to the HTTP request, or adding some kind of ‘qualifier’ to the basic URI (for example, a .xml or .pdf suffix).

Representations can (and in the view of the authors, should) provide links to related resources - in fact this ability to link to other resources is the source of much of the power and attractiveness of the ReST model. This ability to identify resources by URI sets ROA apart from SOA. As the authors note, an SOA application normally has few URIs, sometimes only one. So it is literally impossible for the result of a service call to identify the related entities (I can’t call them resources) for that call. Instead, the client-side programmer must understand the documentation (possibly by poring over the service’s WSDL description) to know how to accomplish any given task. Unless the service designers used great care, the service calls within the SOA application bear little relationship to one another, so understanding some portion of the API provides no great insight into the remainder of the API. The situation is (or can be) different in an ROA application: knowing the set of basic resource types gives immediate knowledge of how to access any particular resource instance. Knowing the relationships between resources (for example, which resources are containers, which resource types are related to other resource types) gives knowledge of how to ‘navigate’ the application - without the service provider having to document every detail of that navigation.

This is exciting stuff. But there are many challenges. At the low end of the scale, there is the issue that browsers know only the GET and POST methods - not DELETE, PUT, and HEAD. So POST has to be overloaded to provide the functionality of PUT and DELETE. At the top end of the scale, it is not clear in any given case what resources should be exposed and what their representation should be. We need a book entitled ‘Resource Oriented Design Patterns’ to fill this gap.

In the meantime, RESTful Web Services is a terrific guide to developing web applications.

Metadata