Building Hypermedia Systems

Building Hypermedia Systems, by Carson Gross, focused on using HTMX.

Enhancing web applications without using SPA framework


Early Excerpts


This is a book about building applications using hypermedia systems

To explain what a hypermedia driven application looks like, and to contrast it with the popular SPA approach of today, we need to first explore the entire hypermedia system of The Web, beyond just discussing HTML.

it is the entire hypermedia system that comes together to make hypermedia such a powerful architecture.

What is a Hypermedia System?

What is a Hypermedia System?

We define a hypermedia system as a system that adheres to the REST-ful network architecture in Fielding’s original sense of this term.

JSON is not a hypermedia, which is an explicit requirement for a system to be considered "REST-ful."

in his dissertation, Fielding was describing The World Wide Web as it existed in the late 1990s.

That system, with its simple links and forms, was what Fielding was calling REST-ful.

Hypermedia-Driven Applications

Hypermedia-Driven Applications

We will call applications built in this style Hypermedia-Driven Applications, or HDAs, and we contrast them with a popular style in use today, the Single Page Application.


The goal of this book is to give you a strong sense of how the REST-ful, hypermedia system architecture differs from other client-server systems, and what the strengths (and weaknesses) of the hypermedia approach are.

Book Layout

we will look at how we can use htmx, a hypermedia-oriented JavaScript library, to improve By using htmx, we will be able to achieve a level of interactivity in our application that many developers would expect requires a large, sophisticated front end library, such as React

Finally, we will look at a completely different hypermedia system, Hyperview. Hyperview is a mobile hypermedia system, related to, but distinct from The Web

Hypermedia: A New Generation

Hypermedia: A New Generation

Hypermedia: A Reintroduction

1. Hypermedia: A Reintroduction

it is rare to see a discussion of HTML as a hypermedia and, more broadly, on how an entire hypermedia system fits together

This is in contrast with the early web development era when concepts like Representational State Transfer (REST) and Hypermedia As The Engine of Application State (HATEOAS) were discussed frequently

we aim to show you that hypermedia is a tremendously innovative, simple and flexible way to build robust applications: Hypermedia-Driven Applications.

Creating a Hypermedia-Driven Application on top of a hypermedia system like the web is a viable and, indeed, often excellent choice for modern web applications

not just web applications

What Is Hypermedia?

1.1. What Is Hypermedia?

Hypermedia is a media, for example a text, that includes non-linear branching from one location in the media to another, via, for example, hyperlinks embedded in the media.

Hyperlinks are a canonical example of what is called a hypermedia control:

Hypertext is a sub-category of hypermedia

Because of this, we prefer the broader term hypermedia systems when describing the underlying architecture of applications built using hypertext, to emphasize the system architecture over the particular hypermedia being used.

A Brief History of Hypermedia

1.2. A Brief History of Hypermedia

While there were many precursors to the modern idea of hypertext and the more general hypermedia, many people point to the 1945 article As We May Think written by Vannevar Bush in The Atlantic as a starting point for looking at what has become modern hypermedia

While Ted Nelson was working on his ideas, Douglas Engelbart was busy at work at the Stanford Research Institute, explicitly attempting to make Vannevar Bush’s Memex a reality. In 1968, Englebart gave “The Mother of All Demos” in San Francisco, California

Modern Implementation

In 1990, Tim Berners-Lee, working at CERN, published the first website

In 2000, Roy Fielding, then at U.C. Irvine, published a seminal PhD dissertation on the web: “Architectural Styles and the Design of Network-based Software Architectures.”

defined the web’s hypermedia network model using the term REpresentational State Transfer (REST).

The World’s Most Successful Hypertext: HTML

1.3. The World’s Most Successful Hypertext: HTML

Rescuing REST From the API Winter,

When HTML 2.0 was released, it introduced the notion of the form tag, joining the anchor tag (i.e. hyperlink) as a second hypermedia control.

It was at this point that the web transitioned from an interesting document-oriented system to a compelling application architecture.

The Essence of HTML as a Hypermedia

The Essence of HTML as a Hypermedia

Anchor Tags

Anchor Tags

Here is what a user interaction with an anchor tag/hyperlink looks like in visual form: An HTTP GET In Action*

Form Tags

Form Tags

Here is a diagram of the interaction: An HTTP POST In Action*

So What Isn’t Hypermedia?

So What Isn’t Hypermedia?

let’s consider a different approach: let’s interact with a server by issuing an HTTP request via JavaScript

crucial aspect of this JSON-based server interaction is that it is not using hypermedia. The JSON API being used here does not return a hypermedia response. There are no hyperlinks or other hypermedia-style controls in it.

Single Page Applications

Single Page Applications

Why Use Hypermedia?

1.4. Why Use Hypermedia?

The Single Page Application offers a far more interactive and immersive experience

JavaScript Fatigue

It turns out that the hypermedia architecture, even in its original Web 1.0 form, has a number of advantages

Single Page Application infrastructure has become extremely complex

JSON API churn, constant changes made to JSON APIs to support application needs, has become a major pain point for many application teams

These two problems, combined with other various issues such as JavaScript library churn, are causing what has come to be known as “Javascript Fatigue”

Why didn’t web developers just stick with it?

We believe that hypermedia hasn’t made a comeback yet for two reasons.

The first is this: the expressiveness of HTML as a hypermedia hasn’t changed much, if at all

It was the user experience that you could achieve in JavaScript (and that you couldn’t achieve in plain HTML) that drove the web development community over to the JavaScript-based Single Page Application approach

Rather than abandoning the hypermedia architecture the industry could have demanded more interactivity from HTML.

There have been heroic efforts to continue to advance hypermedia outside of HTML, efforts like HyTime, VoiceXML, and HAL

A Hypermedia Resurgence?

1.5. A Hypermedia Resurgence?

in the last decade a few idiosyncratic, alternative front end libraries have arisen that attempt to get HTML moving again. Ironically these libraries are written in JavaScript, the technology that supplanted HTML as the center of web development. However, these libraries use JavaScript not as a replacement for the fundamental hypermedia system of the web.*

Hypermedia-Oriented Javascript Libraries

Hypermedia-Oriented Javascript Libraries

One such hypermedia oriented library is htmx, created by the authors of this book.

Hypermedia-Driven Applications

Hypermedia-Driven Application (HDA) A web application that uses hypermedia and hypermedia exchanges as its primary mechanism for communicating with a server.*

an htmx implementation

As with the JavaScript powered button we can see that this button has been annotated with some attributes. However, in this case we do not have any JavaScript scripting going on. Instead, we have declarative attributes much like the href attribute on anchor tags and the action attribute on form tags.*

The HTTP response from the server is expected to be in HTML format, not JSON

When Should You Use Hypermedia?

1.6. When Should You Use Hypermedia?

Applications like Amazon, Ebay, any number of news sites, shopping sites, message boards and so on don’t need a massive amount of interactivity to be effective: they are mainly text and images, which is exactly what the web was designed for.

In any of these cases, using a hypermedia approach would likely be a great choice

When Shouldn’t You Use Hypermedia?

1.7. When Shouldn’t You Use Hypermedia?

One example that springs immediately to mind is an online spreadsheet application

This is simply not a situation amenable to the “large-grain hypermedia data transfer” approach of the web

Hypermedia: A Sophisticated, Modern System Architecture

1.8. Hypermedia: A Sophisticated, Modern System Architecture

Components Of A Hypermedia System

2. Components Of A Hypermedia System

2.1. Components Of A Hypermedia System

The Hypermedia

The Hypermedia

Hypermedia Protocols

Hypermedia Protocols

HTTP Methods

HTTP Methods




A strange thing about HTML is that, despite being the world’s most popular hypermedia and despite being designed alongside HTTP (which is the HyperText Transfer Protocol, after all!), the native hypermedia controls in HTML can only issue HTTP GET and POST requests

it is hard to understand why this hasn’t been fixed in the HTML specification yet!

HTTP Response Codes

HTTP Response Codes

Caching HTTP Responses

Caching HTTP Responses

Hypermedia Servers

Hypermedia servers are any server that can respond to an HTTP request with an HTTP response

Hypermedia Clients

Hypermedia Clients

The canonical example, of course, is the web browser

Browsers aren’t the only hypermedia clients out there, however. In the last section of this book we will look at Hyperview, a mobile-oriented hypermedia


2.2. REST

The term “REST” comes from Chapter 5 of Roy Fielding’s PhD dissertation on the architecture of the web

The “Constraints” of REST

The “Constraints” of REST



The Client-Server Constraint

he was describing the network architecture of the World Wide Web, and contrasting it with earlier architectures, notably thick-client networking models such as the Common Object Request Broker Architecture (CORBA

The Statelessness Constraint

The Statelessness Constraint

In practice, for many web applications today, we actually violate this constraint: it is common to establish a session cookie

The Caching Constraint

The Caching Constraint

cache-ability of responses for future requests of the same resource

The Uniform Interface Constraint

The Uniform Interface Constraint

REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state

Identification of Resources

Identification of Resources


any sort of data that can be referenced, that is, the target of a hypermedia reference, is considered a resource

Manipulation of Resources Through Representations

Manipulation of Resources Through Representations

Self-Descriptive Messages

Self-Descriptive Messages

This means that all information necessary to both display and also operate on the data being represented must be present in the response. In a properly REST-ful system, there can be no additional “side” information necessary for client to transform a response from a server into a useful user interface.

notice that the HTML representation has a hyperlink in it to navigate to a page to archive the contact. The JSON representation, in contrast, does not have this link

the JSON API client must know in advance exactly what other URLs (and request methods) are available for working with the contact information

clients (that is, web browsers) don’t need to understand anything about the underlying resources being represented

This gives hypermedia-based systems unprecedented flexibility in dealing with changes to both the backing representations and to the system itself

Hypermedia As The Engine of Application State (HATEOAS)

Hypermedia As The Engine of Application State (HATEOAS)

A client interpreting the JSON response must, again, understand not only the general concept of a Contact, but also specifically what the “status” field with the value “Archived” means (Basically, preferring a dumb client. But if you're delivering the smart client as JavaScript in real time, does it matter?)

This approach is certainly not using Hypermedia As The Engine Of Application State: rather, it is using a javascript model as the engine of application state, and synchronizing that model with a server and with the browser


Edited:    |       |    Search Twitter for discussion