RESTful Web Clients: Enabling Reuse Through Hypermedia

by Mike Amundsen

Powerful web-based REST and hypermedia-style APIs are becoming more common every day, but instead of applying the same techniques and patterns to hypermedia clients, many developers rely on custom client code. With this practical guide, you'll learn how to move from one-off implementations to general-purpose client apps that are stable, flexible, and reusable.

Author Mike Amundsen provides extensive background, easy-to-follow examples, illustrative dialogues, and clear recommendations for building effective hypermedia-based client applications. Along the way, you'll learn how to harness many of the basic principles that underpin the Web.


Convert HTML-only web apps into a JSON API service
Overcome the challenges of maintaining plain JSON-style client apps
Decouple the output format from the internal object model with the representor pattern
Explore client apps built with HAL--Hypertext Application Language
Tackle reusable clients with the Request, Parse, Wait Loop (RPW) pattern
Learn the pros and cons of building client apps with the Siren content type
Deal with API versioning by adopting a change-over-time aesthetic
Compare how JSON, HAL, Siren, and Collection+JSON clients handle the Objects/Addresses/Actions Challenge
Craft a single client application that can consume multiple services

Genres: Software, Technology

550 pages, Kindle Edition

Published February 13, 2017

Reviews

[Colton Kopsa · Rating 4 out of 5]

tl;dr: great book for offering me a paradigm shift when thinking about web APIs; however, seeming lack of adoption makes me skeptical to use in production. So, I’ll probably try it out with a side-project.

To be honest, this book blew my mind. It opened me up to a new way of thinking which was utilizing media types over versioning schemes, and approaching the task of API design with the intent to maximize loose-coupling. I had never considered those ideas previously, and it was very enlightening to see a new perspective. The idea of reusable clients also blew my mind. Having written a few web UI clients myself, I always feel that I’m putting too much logic in them, and that they’re going to be too difficult to test. Given the approach from this book, I now feel like it’s possible to have 0 business logic in your UI and have it be very easy to test. All of this makes me very excited to try it out.

That being said, when I go to try it out, or make a convincing case for my company to try it out, I feel I’m faced with a wall. The light adoption of these concepts 3 years after this book was released (or even more than that given previous books about hypermedia-based APIs) gives me the feeling that I would be acting all-in-all alone in the world of development while migrating/creating projects to/with this way of thinking. Some examples of this are the 3 media types spoken about (HAL, Siren, and Collection+JSON), besides HAL on AWS, none of them really seem to have any widespread adoption. CJ is the only one to have the proper schema for objects, actions, and addresses, but I don’t know who is using it, and what their experience has been. The other example is the semantics definitions. ALPS and DCAP. Neither are really battle-hardened it seems. My Google-foo revealed limited information about ALPS outside of the main website, and couldn’t even find DCAP. I did eventually find DCAP from an article from Amundsen on infoq. And I’m okay that it feels obscure, so does LISP and I love it. That being said, LISP has a better track record (NASA, game engines, Yahoo sites, air traffic control, Clojure), and that gives me some confidence about using it when the stakes are high. It’s probably not a proper comparison, but it’s a comparison nonetheless.

Hypermedia Rant? Inquiry?

Which brings me to my question: Why hasn’t the industry gone all in on full RESTful APIs (HATEOAS)? Is it because it’s too hard? Are the benefits not really there? Do few applications actually warrant the flexibility it provides? Is everyone doing it in secret? It it more of a hobbiest thing? Where are the testimonials? Stack-overflow posts? Quora? (I know there are some, but not nearly as many as I feel would be adequate to signify medium adoption rate). Maybe I just need to do some more research, but that’s where I’m at right now.

[Juri · Rating 2 out of 5]

This book is kind of an extensive version of “Building Hypermedia APIs with HTML5 and Node” by the same author. In both books, he gives an overview of hypermedia in Web APIs and shows how to implement client and server code in vanilla JavaScript. In this book, there's some more background info and best practices in between the implementation chapters. The hypermedia types he discusses are HAL, Siren and Collection+JSON. (In the book mentioned above he discusses Maze+XML, Collection+JSON and HTML.)

Generally I support the ideas presented in this book, but as already “RESTful Web APIs” this book is too much tailored around the media type that was created by the author himself (Collection+JSON). While reading it seemed to me like an elaborate advertisement for using the Collection+JSON media type. (The permanent mentioning of how a Collection+JSON document looks like was already annoying when reading “RESTful Web APIs”, but here it's even more obvious.) Strangely enough, none of the given links to GitHub repos or running examples for HAL and Siren seem to work, only the ones without hypermedia controls and of course Collection+JSON... (a coincidence?)

[Jorge · Rating 4 out of 5]

This book is a gem. The current trend in developing APIs and clients assumes that it's fine to break backwards compatibility every so often. But there is a better way and this book clearly guides us through a path to building never breaking clients.

The only reason I'm not giving it 5 stars is because the writing style could be a bit better, making the great content shine more.

[Parinya Chavanasuvarngull · Rating 5 out of 5]

เปิดโลกการพัฒนา Microservices ในแบบของ Hypermedia (อีกแบบคือ Messaging) ให้ผมเลยทีเดียว... ;)