« Plagiarism awareness and information skills for teachers | Main | When two identifiers for the price of one is not a good deal »

January 07, 2007

Thinking about REST, Part 1: Developing a Resource-Orientation

Prompted partly by some of Andy's earlier posts about ensuring that the applications we (and I guess I'm thinking here of the digital library and e-learning communities, but it applies more broadly too) develop are designed so as to be a good "fit" for the Web, I've been trying to follow up some of the contributions to the wider debates about the nature and design of Web applications.

Really, this post isn't much more than a brief collection of jottings - bookmarks and the occasional quotation - but I hope that the resources I point to may be of use to others, and that the points I highlight here might help to clarify some of the arguments I'll make in other posts.

One of the most helpful resources I've come across recently is a presentation by Stefan Tilkov titled "REST - The Better Web Services Model" (both slides and audio are available). It provides a very clear and comprehensive introduction to the "Representational State Transfer" "architectural style", which is an abstraction defined by Roy Fielding to articulate the key architectural priciples underpinning the Web and the HTTP protocol, and to the way features of HTTP implement the REST style. He moves from the general to the specific and discusses how to design a RESTful application, and contrasts this approach with that taken by the "Web Services" family of specifications, concluding on the "provocative" note: "If you only remember one thing, it should be that HTTP is good enough". I found it an excellent presentation and I'd strongly recommend giving it a listen.

The presentation also mentions the notion of REST-based architectures supporting a "resource-oriented approach", and the contrast between a "resource-oriented approach" and a "service-oriented approach" is explored further in a piece by Alex Bunardzic titled "Replacing Service Oriented Architecture with Resource Oriented Architecture". And covering similar ground, Leonard Richardson and Sam Ruby have a note summarising the content of their forthcoming book, REST Web Services:

We want to restore the World Wide Web to its rightful place as a respected architecture for distributed programming. We want to shift the focus of "web service" programming from an RPC-style architecture that just happens to use HTTP as a transfer protocol, to a URI-based architecture that uses the technologies of the web to their fullest.

Richardson and Ruby also highlight that "using REST" is not the same thing as "not using SOAP"; some systems that are loosely labelled as "REST-based" do not in fact respect the constraints of the REST architectural style.

Although I enjoy working with some level of abstraction, more often than not, particularly when I'm coming to something new, the light bulb in my head tends to flicker somewhat intermittently until someone shows me an example. Tilkov's presentation also points to a piece by Joe Gregorio, "How to Create a REST Protocol" which works through the design of a real application and highlights the key steps:

  1. decide on the resources required for your application, and select URIs to identify those resources
  2. decide the formats to be used for representations of resources
  3. decide which of the REST methods/verbs are to be supported by each resource i.e. how do the functional requirements of the application map to the uniform interface specified by REST?
  4. decide which response codes are to be returned by each resource

Gregorio's article includes a pointer to a brief list of potential pitfalls by Paul Prescod, of which I'll only highlight a few here:

4. Do not put actions in URIs.  This follows naturally from the previous point [about URI opacity]. But a particularly pernicious abuse of URIs is to have query strings like "someuri?action=delete". First, you are using GET to do something unsafe. Second, there is no formal relationship between this "action URI" and the "object" URI. After all your "action=" convention is something specific to your application. REST is about driving as many "application conventions" out of the protocol as possible.

5. Services are seldom resources. In a REST design, a "stock quote service" is not very interesting. In a REST design you would instead have a "stock" resources and a service would just be an index of stock resources.

8. Do not worry about protocol independence. There exists only one protocol which supports the proper resource manipulation semantics. If another one arises in the future, it will be easy to keep your same design and merely support the alternate protocol's interface. On the other hand, what people usually mean by "protocol independence" is to abandon resource modelling and therefore abandon both REST and the Web.

OK, that's it for now. More to come as I think a few things though, I promise!


TrackBack URL for this entry:

Listed below are links to weblogs that reference Thinking about REST, Part 1: Developing a Resource-Orientation:


Hi Pete,

Kimbro Staken posted "10 things to change in your thinking when building REST XML Protocols" some time ago which I found complemented the Joe Gregorio piece - both are pragmatic, useful cribs.

Kimbro's post is here:


The comments to this entry are closed.



eFoundations is powered by TypePad