REST 1/n

I’m reading REST: from research to practice and, although I have barely started it, I can’t recommend it. It’s an academic book, each chapter written by different authors, more similar to a collection of papers than a real book. If you want to learn about REST from a purist viewpoint, read RESTful Web APIs instead.

But reading this book I’ve noticed that I haven’t talked about REST (apart from a review of another book) in the blog and I’ve been working on a REST library for a year (!).

I just wanted to point out several tidbits of the book… the first one being the definition of REST:

REST is a set of constraints that inform the design of an hypermedia system.


The claim of REST is that following those constraints will result in an architecture that works well in the areas of scalability, mashup-ability, usability, and accessibility.

REST is just a set of constraints and that is, per se, a very nebulous definition and makes it impossible to say if an API is REST or not. You can only say that it tries to apply some of the constraints or not. But there are several maturity models, Richardson’s is the one used as the cover image for this blog.

The constraints (as defined in the book, there isn’t a uniform set either) are:

  1. Resource Identification: all resources should have unique and stable identifiers. These identifiers can be referenced across the API/application.
  2. Uniform Interface: self-explaining, expose resources and resource interactions that only use the uniform interface, or a subset of it (like the HTTP verbs).
  3. Self-Describing Messages: the representation of the resources should be self-documented, the purpose of the fields or their semantic should be obvious by reading the representation.
  4. Hypermedia Driving Application State: resources are supposed to be linked, so that an application will be able to use them, discover new resources or new fields, this constraint allows loosely-coupled systems.
  5. Stateless Interactions: there should be no client state (scalability!).

This sounds easy but it’s really hard and there is always to fear of betting everything (or following all constraints fully) will lead to no benefit than just ditching one.

The Essence of REST Architectural Style

The first chapter of the book discusses the definition of what an architecture style is and tries to create a model to represent REST constraints. They use the model to analyze ROA (Resource-Oriented Architecture) and derive the conclusion that ROA lacks only one decision compared to REST: “Hypermedia as the engine of application state”.

And they try to guess that ROA proponents drop it because it hurts performance and makes API development harder. “The additional effort is not considered worthwhile when compared to the benefits of Scalability and Modifiability”. Ouch.

And that’s all for the chapter… IMHO I find those models neither interesting nor scientific. You can skip this chapter.

Last words (for now)

I’ve given several talks on REST and Hypermedia… these are the slides I’m most proud of (because the theme is based on Cindy Lauper, and Cindy Lauper is God).

I’m on twitter at nhpatt if you want to read more, sporadic, ramblings :)