Book Review: RESTful Web Clients

RESTful Web Clients is written by guru Mike Amundsen who amongst other things co-authored RESTful Web APIs with REST guru Leonard Richardson and Sam Ruby.

The book's primary focus is on the hypermedia aspect of REST, particularly from the client's perspective.   As Roy Fielding detailed in this famous blog post "if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API"  and let's face it, we have all seen APIs purporting to be REST with no hypermedia whatsoever with lots of coupling between client and server.  Some of this is just down to basic ignorance and some of it probably down to misunderstanding the Richardson Maturity Model

Rather than begin with a summary of Fielding's dissertation like most material on REST, this book  begins with details of a simple web application that uses JSON RPC APIs.  From the simple example Amundsen shows that while the JSON RPC approach functionally works, it results in a lot of coupling between client and server meaning that if the APIs need to change it will be difficult to do that easily as the client(s) with all its hardcoded of contracts will be impacted.  And we know software does need to change from time to time right?

Amundsen distills the coupling with the JSON RPC approach into three distinct types which can be considered and assessed individually:

• Objects - the JSON objects that appear in API responses.  Clients need to be able to understand them to handle a simple a response to a GET request
• Addresses - the URLs clients needs to know to invoke requests
• Actions  - details methods and arguments for all non-trivial operations. Again clients need to know this before invoking requests.  

With the coupling clearly demonstrated, the scene is nicely set to move onto one of key advantages of a REST style archictecture: reducing coupling through hypermedia.

To explain this advantage, Amundsen again uses the approach of specific examples.  Firstly, by detailing the  JSON hypermedia type HAL.   Using this approach reduces the Address coupling and examples of how generic response handling can be written on the client to leverage and take advantage of this decoupling are detailed.  However HAL doesn't solve everything.  Without a custom extension there is still coupling to the JSON Objects and the possible Actions available to the client.  A work around to this is given and I would highly recommend anyone considering using HAL to read Chapter 4.

Next up is another JSON hypermedia type known as Siren.  Kevin Swiber designed Siren and registered it with IANA in 2012.

Siren splits response entities into:

• class  - this is an array, the values of which indicate what the current resource represents e.g. Customer, Person
• properties - set of name-value pairs
• entities - a list of linked and representational sub entities
• actions - contains a set of valid operations of the associated entity and how to invoke those operations including a list of fields which match HTML5 input types (hidden, text, number).  This is something not in HAL that helps reduce client-server coupling further
• links - links to other resources.  Each link has a class, href, rel, title, type property

Siren  reduces coupling to Addresses and Actions, however it does not reduce coupling to Objects.  There is no meta-data specification for the class type meaning the client has to hardcode the structure of the object somewhere.   Like HAL it is possible to create a custom extension but this is not part of the Siren specification.

The third hypermedia type detailed is Collection+JSON format (Cj). Interestingly, this format was designed by the author himself.    The basic elements of a Cj message are:

• Links - Simlar to HAL and Siren links
• Items - Similar to HAL and Siren properties and also includes meta data about the properties
• Queries - Information on how to construct various reads (HTTP GETs)
• Templates - Information on how to construct various writes (HTTP POSTs, PUTs, DELETEs...)
• error - information ref errors

The key point here is that since Cj includes the metadata about the items, it decouples the client from the Objects in the JSON responses something both HAL and Siren could only achieve with custom extensions.

So which format? Well two good points to make here:

1. That can be a practical decision and not just a technical one.  You may prefer Cj because out of the box it achieves most decoupling, but your customer may be used to and prefer HAL.
2. Rather than trying to support every possible format, think about architecting so it possible to support extra formats if you need to.  The approach suggested is described in the Amundsen's Representor pattern - which is inspired from the Message Translator  Pattern

So in summary, this is another great REST book from O'Reilly.  The style of the book in general is pragmatic rather than academic.  It really emphasizes and demostrates the importance of hypermedia in REST APIs and is backed up with practical examples.  The central argument in the book is that Cj achieves the most decoupling.  Even if it was written by the author, the argument is well made and I don't think it would be fair to make accusations of any selection bias since he does detail how you can extend Siren and HAL to achieve the same level of decoupling.

Bottom line - if you want to understand the hypermedia aspects of REST, read this book.