Book Review — Hypermedia Systems
I’m not a web developer (see the “Background” section below). At best, I occasionally hack a small web application for an operational project that I’m working on. Truthfully, I’ve been thoroughly scared off from the web ecosystem by the trend of releasing a new Javascript framework on each day ending in “day.” I came across the HTMX project about a year ago, and filed it away in my brain under the “huh, that seems cool” category. I never expected to really pick it back up again.
A few months ago, something brought me back to the HTMX website, and I noticed the library authors had written a book: Hypermedia Systems. I decided to give it a read despite my general lack of web prowess. What I found delighted me. I hope this brief review encourages you to discover the lost joy of building robust web applications using simple, yet elegant, technology.
Background
If you’re not interested in a prosaic description of how I got here, then feel free to skip to the next section. However, I’d encourage you to give the next few paragraphs a read: I think they’ll resonate with you.
I started learning about building websites during the summer between 5th and 6th grade. I still remember lounging around on hot summer days reading a book about HTML and CSS. The evenings were spent applying what I had learned on a (presumably cracked) version of Macromedia Dreamweaver. I distinctly remember making a typo when trying to use my first img tag. I was using scr instead of src for the “source” attribute, and my image wasn’t appearing. Puzzled, I emailed the book’s author because I couldn’t spot my mistake. She couldn’t spot the error either, but using Macromedia to insert the image instead of typing out the HTML worked, so I moved on.
Those were better times, before the era of social media and the startup rat race, when computing was legitimately fun. I still remember the sense of awe that I felt as I saw my imagined web creations come to life on a 12-inch deep CRT monitor. I continued to dabble with a few small-town paid web design gigs, but I eventually moved away from web development into the world of operations and systems administration.
A few years ago, I started pulling the web design thread again. I was dismayed to find that the landscape had radically changed. Every new website seemed to be a giant, complex organism involving monolithic front-end web frameworks with confusing concepts like “data binding,” “content projection,” and “dependency injection.” I couldn’t even begin to make sense of most modern web development tutorials, and it seemed like there was no point anyway: there were no solid web frameworks, merely the web framework du jour. I buried myself back in the Linux terminal and vowed never to emerge again.
Some time passed, and I noticed that others in industry were beginning to feel the same way: projects like HTMX and Hotwire emerged, and I mentally filed it away that others were starting to reject the smell of giant single page web applications (SPAs). This sounded promising, but I still hid myself back in Apache configs and Ansible playbooks, preferring to maintain web services without peeking too far into the code that ran them.
I decided to revisit HTMX recently because I wanted to build a small personal web app. I was interested to see that the authors of the project had written a book: Hypermedia Systems. With my first child on the way in a few weeks and a litany of other responsibilities, I decided there was no better time to dive into a new technical book. What I found truly restored that sense of joy that I had back in the summer between 5th and 6th grade.
Summary
Hypermedia Systems follows a logical path beginning with a background in hypermedia, the theory of Representational State Transfer (REST), and a basic history lesson in Web 1.0. If you’ve been in the industry for awhile, it’s funny to think about the need for a Web 1.0 reintroduction, but it makes perfect sense: there’s currently an entire generation of engineers who didn’t spend time building websites with blinking fonts and page view counters. The background and theory section of the book are excellent, and they’re worth the entire book itself. If you choose not to read any further due to a lack of interest (or preexisting expertise) in HTMX, then you should at least read the Hypermedia Concepts section.
The book continues with an introduction of HTMX to build a simple but relatively realistic web application: a contacts management app. The authors gradually introduce HTMX concepts, drawing parallels (and cheeky criticisms) with SPA frameworks where appropriate. While basic, the web app isn’t just a toy example. The authors go to great lengths to demonstrate the real-life applicability of HTMX in building a web application with a 21st century user experience (UX). They even mix in some client-side scripting with _hyperscript.
Finally, the authors spend some time applying the hypermedia paradigm to mobile applications using Hyperview. The web application that you previously developed is now extended to support a mobile platform. Once again, the book works hard to show you that modern mobile applications can be built using the hypermedia approach. I admittedly skimmed this section without carefully considering the code examples, but that wasn’t because the content was poor. On the contrary, I think Hyperview and the book’s discussion of it are very exciting. However, I simply don’t have any plans to develop mobile applications, so this section wasn’t as applicable me.
I appreciate the book’s natural progression from theory to web to mobile use cases. There’s something here for everyone, and the book is written to facilitate skipping around. I could have entirely skipped the section on mobile development without losing out on the book’s main purpose. Likewise, if you’re already comfortable with HTMX but want to apply hypermedia to mobile applications, then you can jump directly to the appropriate chapters.
The Good
Hypermedia Systems is one of the most fun books that I’ve read recently. With a careful bit of snark directed at the apex predator of complexity, the authors do an excellent job of making the case for hypermedia in the modern web ecosystem. More importantly, this book and the HTMX library that drives it make web development fun again. Instead of a rat’s nest of complexity and a dizzying array of weird client/server state management concepts that accompany SPA development, this book shows how to build a fairly robust web application using simple tools. I can’t stress enough how refreshing this simplicity is: I was able to immediately start applying the concepts in the book to build my own web app without a PhD in ReactJSNativeBlockchain4.0.
The theory section, and the importance and applicability of hypermedia, is the strongest selling point for this book. A grounding in the historical basis of the modern web is important for any engineer, irrespective of their opinion on HTML and hypermedia. The authors make a strong case for the relevance of hypermedia in modern web design. In many ways, a hypermedia architecture simplifies an application beyond just reducing JavaScript overhead. Rather, the Hypermedia As the Engine of Application State (HATEOAS) principles truly simplify the application itself. There is no need for strict API contracts or documentation when the entire application interface can be discovered and navigated organically.
The use of a realistic web application helps to make the case for hypermedia being a tool in the modern web development toolbox. I imagine that many will be skeptical of a book that primarily advocates for HTML, CSS, and very little JavaScript. The use of a realistic application, with modern UX features, assuages this concern and makes the book applicable to real use cases that a reader likely has. The power and realistic applicability of hypermedia is summarized by one of my favorite quotes of the book at the end of Chapter 7:
In this chapter we’ve managed to create a dynamic UI for our contact archive functionality, with a progress bar and auto-downloading, and we’ve done nearly all of it — with the exception of a small bit of scripting for auto-download — in pure hypermedia. It took about 16 lines of front end code and 16 lines of backend code to build the whole thing.
Finally, the prose itself is engaging and approachable. The authors weave in plenty of humor, which is no surprise given that Carson Gross is the author of the Grug Brained Developer. The code examples are easy to follow, even for those with minimal background in the chosen backend framework (Python’s Flask). As someone who takes forever to read technical books, I was able to burn through Hypermedia Systems quickly from the comfort of my Kindle. Strong content paired with great readability make Hypermedia Systems a joy to read, and it renewed my long lost childhood sense of wonder about web design.
The Bad
Overall, I have few criticisms of Hypermedia Systems. It does a good job of (re)introducing the power of hypermedia and teaching the reader about the HTMX framework.
The book preaches an HTML/XML/Hypermedia purism that some might find off-putting. I do believe that JSON-based HTTP APIs can implement something approaching HATEOAS, as seen with projects like the Redfish API for server management. Redfish exposes the application in a way that allows for interactive discovery and management, without prior knowledge or API documentation. However, this purism is an understandable reaction when the overwhelming majority of “REST APIs” on the market today are simply “JSON HTTP APIs“ devoid of the REST constraints enumerated by Roy Fielding.
A JSON-based HTTP API is a table stakes requirement for most modern web applications. We can debate the merit of this, but it is the reality of modern application development. Users expect programmatic interaction, typically with JSON. The authors mention this reality, and describe segmenting web routes so that you have both hypermedia routes (for the UI) and JSON-driven routes (for a programmatic API). However, their brief treatment of this topic falls a bit short. It was on my mind throughout the entire book, and the same is probably true of many readers. A more robust discussion of this requirement, especially how it has been handled by real applications that implement hypermedia, would have been appreciated.
Again, these are relatively minor nit-picks, and you could argue that they are somewhat beyond the scope of the book. However, they are important for hypermedia evangelization. We must remember that an entire generation of engineers has cut their teeth on “put the component inside the data hydrator with the asynch API pulling data from v1.3.2-rc1 of the JSON API,” and overcoming the bias toward such mind-numbing complexity will be challenging.
The Verdict
Hypermedia Systems is a well-balanced book full of quality arguments, good humor, and robust code samples. It should be a must-read for any web application developer, especially since it’s completely free online (though I’d encourage you to support the authors and spend $9.99 for the eBook).
Finally, I encourage anyone building a new web application to seriously consider the power and simplicity of a hypermedia and HTMX-driven design. You have nothing to lose: whatever Javascript framework you choose will likely be out of date by the time you have a minimum viable product anyway. Yet you have much to gain: the simplicity of a hypermedia-driven application will allow you to spend your complexity budget elsewhere. And that’s really why Hypermedia Systems resonated with me so much: any simple tool that reduces complexity in the long run is a breath of fresh air in the modern technology landscape.
