Elisabeth Robson

I picked up Building Hypermedia APIs with HTML5 and Node by Mike Amundsen hoping to learn more about HTML5, Node.js and how they are used to build web applications. Instead, the book primarily offers specific hypermedia solutions to the “type-marshaling” problem, that is, the problem of communicating between clients and servers. For instance, if the server publishes a schema that the client uses, and then that schema changes, all the clients break.

The “hypermedia solution” proposes to create HTTP-based communication protocols that use meta data to make the data being communicated less fragile. For instance, the JSON chapter shows how to design meta data so that the server can communicate the queries that are allowed by the client. (One problem I have with the book is that the author doesn’t describe what happens when the schema for the meta data changes! This issue is not addressed, as far as I could tell.)

I found this book difficult to read. For instance, the first chapter, where the author sets up the reason why we would use Hypermedia APIs, to be overly abstract and vague. The examples are not described or described poorly, and leave a lot out. E.g. on page 8 the author writes, “For example, [these type-marshaling patterns] are very server-centric; they meet the needs of server developers but usually leave client programmers to fend for themselves.” The author never explains what “server-centric” means or why, exactly, the client programmers are left to fend for themselves. In the examples that follow that set up why we need better type marshaling, none of the code is explained, so the reader is left to figure out how the code illustrates the text.

And on page 11, where the author first introduces a Hypermedia solution, there is similar vagueness, especially where the author states that the example “conveys the idea” without ever explaining it (and the fact that there is a technical error in this first example further complicates things). When I’m learning something new, and I’m only on page 11 and it’s the first example of a new idea I’ve seen, I’d like to see things spelled out a bit more! Unfortunately, this is typical of the entire book; much of the material is left for the reader to figure out on her own.

The author defines “hypermedia” in the middle of a paragraph with a sentence that is difficult to parse, and difficult to understand:

“This kind of application metadata allows the client to modify the state of the application, and to drive the application forward in a way that gives the client the power to add, edit, and delete content, compute results, and submit filters and sorts on the available data.”

The author says, “This is hypermedia.” What does it mean for a client to “drive an application forward.”? I have no idea! And while it is fairly obvious to the seasoned programmer that the point of a client-server application is to allow the client to “add, edit, and delete content,” etc., neither this sentence nor the paragraph it’s in explain at all why and how this is related at all to hypermedia.

Unfortunately, the chapters that walk the reader through the client-server examples aren’t much better. They read more like manuals than a book, presenting every single option the application will implement, explaining each in detail. Much of the content in these chapters is presented as code listings and the reader is expected to slog through these with minimal help from the author.

Finally, I found the writing overly passive and formal, which makes the book hard to follow in places. I also think that at times, the author makes the topic far more complicated than it needs to be (particularly with the H-factors which attempt to classify linking and HTTP control methods). While much of the information is important and potentially interesting, it would have been much better presented in context with the examples where it is needed, with a summary at the end. In many places in the book, I felt like I was reading someone’s dissertation, not a book that I’m supposed to be learning from.

In sum: I think some of the ideas presented in this book are valuable, however they are lost in the complexity of the presentation of the material. I can only recommend this book if you are already an expert in the technologies used (Node.js, XML, JSON, HTML) and interested in the specific examples the author is showing because you need to build a similar application. This is most definitely not a book to learn from, particularly if you are new to Web technologies. It is more like a reference manual for several different specific examples of hypermedia applications.