Author: Jim Webber, Savas Parastatidis & Ian Robinson
Publisher: O'Reilly, 2010
Aimed at: Programmers who want to think about REST
Cons: Over long and often off topic
Reviewed by: Mike James
With the subtitle "Hypermedia and Systems Architecture" does this book help the developer who wants to get to grips with REST?
REST - Representational State Transfer is becoming increasingly popular as a way of implementing Web based APIs. Gone are any suggestions that SOAP or something complicated might be what we need - REST is simple, easy to implement and easy to use. However, if you read this book you might well be convinced that REST is incredibly complicated and a matter that might be discussed as part of a philosophy degree.
Many programmers think that REST simply means using a URL as a remote procedure call mechanism, and indeed it is, but there are also ideas, guidelines and rules that augment this simple idea. The motivating principle is that your use of REST should be as much like the way a normal web page works as possible - that is a REST API should fit in with the conventions of the web. In addition it should be well-designed and so far all this seems very reasonable.
This book introduces REST in the widest possible terms using an example of a coffee shop processing system called Restbucks. The first chapter starts off with a look at the structure of the web and how to use URIs to identify resources. This is where the philosophy starts - the distinction between URI, URN and URL is an important but minor one and yet the book goes on for pages in a way that seems designed to confuse. Then we have the idea of resource representation as distinct from the resource itself. Most programmers would or should be happy with this idea and really don't need it reiterating or even defining as:
" a transformation or a view of a resource's state at an instant in time."
All good stuff but well away from the mucky machinery of code and it just serves to make the whole thing seem more abstract and theoretical. Finally we have a lightning overview of the HTTP verbs and some waffle about loose coupling and other desirable design features. This is all relevant, it is just not well presented in a clear and direct format.
Chapter 2 launches on a description of using GET to get a cup of coffee. We are into modeling with pictures of people with speech bubbles showing the basic transactions. Then XML for a representation and that's more or less where it ends. Chapter 3 continues on with more diagrams showing transactions. URI templates, URI tunneling and plain old XML over HTTP. In this chapter we get to some code fragments - C# and Java. There is no real need for a book on REST to have any code in it but there is a real need for it to be clear about what REST is and at page 47 you almost certainly don't have any clear ideas about anything.
Chapter 4 is on CRUD web services, which you might think was such a core REST issue it would occur earlier in the book. This at last starts to get real - it shows you how to map the HTTP verbs to your application, or rather to the Restbucks application. In many ways this is the core chapter for any reader wanting to know about REST - but it is very short and it could do with a sensible introduction to the reasons why things are best done in this way. This is almost the only complete chapter that fulfils the promise of the "in Practice" part of the title.
Chapter 5 goes beyond basic REST to consider how hypermedia can represent application state. This is perhaps the densest part of the book. It makes very heavy going of a very simple idea. If you are prepared to dig through it then you will, with luck, get the idea. Chapter 6 is about scaling and is mostly a discussion of caching. Chapter 7 and 8 is a description of the Atom syndication format which is generally considered to be a reference REST implementation but do we really benefit from having it explained in such depth?
Chapter 9 is about web security - mostly HTTPS with a side serving of authentication. Chapter 10 is on semantics - yes the semantic web and in my opinion this is well off topic. Then Chapter 11 deals with web services - Soap v Rest and asks are web services evil? Given the topic of the book the answer is yes. The final chapter is a throwaway "making the case for the web". If you have got to end of the book and need to read this you really weren't concentrating.
This book tries to deal with the overall philosophy of REST but you could read it from end to end and still not have got the idea or the objective. The book is simply not clear spoken enough and it is far too long - which is presumably the reason it goes off topic at various points. The principles of REST can be explained in a few chapters as long as your concern is to explain the idea rather than wrap the whole thing up in a sophisticated language that makes it seem profound.
I'm sure that some readers will find it useful but for what I'm not sure....
The truth about REST