Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Book Review: RESTful Web Clients

DZone's Guide to

Book Review: RESTful Web Clients

We take a look at O'Reilly's RESTful Web Clients book and see what it's about--and if it's worth picking up. Read on for the review!

· Integration Zone
Free Resource

Share, secure, distribute, control, and monetize your APIs with the platform built with performance, time-to-value, and growth in mind. Free 90 day trial 3Scale by Red Hat

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.

Image title

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 need 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 architecture: 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 workaround 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 - Similar to HAL and Siren links.
  • Items - Similar to HAL and Siren properties and also includes metadata 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 demonstrates 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. 

Discover how you can achielve enterpriese agility with microservices and API management

Topics:
rpc ,hypermedia ,json ,integration ,web client ,rest

Published at DZone with permission of Alex Staveley, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}