Components of a Hypermedia System

2026-08-08 · page · source ↗ · source summary

The canonical theoretical foundation for hypermedia-driven web applications, drawn from Carson Gross et al.'s book Hypermedia Systems. This chapter decomposes the web into four components (hypermedia, protocol, server, client), then traces through Roy Fielding's REST architectural constraints — particularly the uniform interface and HATEOAS — to explain why hypermedia systems are more flexible than JSON APIs and what "RESTful" actually means.

Key Quotes

"REST, as coined by Fielding, describes the pre-API web, and letting go of the current, common usage of the term REST to simply mean 'a JSON API' is necessary to develop a proper understanding of the idea."

The authors' central polemic. Fielding wrote his dissertation before JSON APIs and AJAX existed — he was describing HTML over HTTP as a hypermedia system. The term "REST" has since been co-opted to mean "any JSON-over-HTTP API," which is not only wrong but structurally impossible: a JSON API without hypermedia controls cannot satisfy the uniform interface constraint. This is the theoretical backing for the HTMX project's entire stance. The practical pages in this wiki — How I Use HTMX with Go, Progressively Enhanced Forms with HTMX, The GUS Stack — Go, Unix, SQLite — are all implementations of this theoretical position.

"The trade-off, though, is that a uniform interface degrades efficiency, since information is transferred in a standardized form rather than one which is specific to an application's needs."

Fielding, quoted by the authors, acknowledging the cost. RESTful hypermedia is less efficient on the wire than a bespoke JSON format. The HTML representation of a contact is larger than the JSON equivalent. The trade is representational efficiency for flexibility: a client that only knows how to render HTML can navigate any hypermedia API without prior coordination. This is the tradeoff that SPA advocates see as a bug and hypermedia advocates see as the feature. It's also the tradeoff that agents don't need to make — an LLM can read both formats — which raises the question of whether REST's flexibility premium matters in an agentic world.

"Hypermedia As The Engine of Application State (HATEOAS). This constraint is closely related to the previous self-describing message constraint."

The chapter's most practically useful section walks through the same endpoint (/contacts/42) returning HTML vs. JSON under three scenarios: active contact, archived contact, and contact with a new "message" feature. In every case, the HTML self-describes the available operations — when the contact is archived, the "Archive" button disappears and an "Unarchive" button appears. The JSON representation is unchanged; the client must know from external documentation what the "status": "Archived" string means and what operations it permits. This is not a hypothetical — it's the structural reason hypermedia APIs don't need versioning and JSON APIs do.

"Due to this flexibility, hypermedia APIs do not have the versioning headaches that JSON Data APIs do."

The chapter's strongest claim, and the one with the most practical consequence. Once a hypermedia-driven application has been entered through an entry-point URL, all further navigation is encoded in self-describing messages. A server can add, remove, or change operations and URLs without breaking clients — the client simply renders whatever HTML it receives. This is why the GUS Stack's "HTMX as much as possible" prescription works: the server owns all application state, and the client is a rendering engine. The tradeoff, as Progressively Enhanced Forms with HTMX documents, is that partial updates create stale-data problems that a full hypermedia client (the browser) was never designed to handle.

"A strange thing about HTML, though, is that the native hypermedia controls can only issue HTTP GET and POST requests."

The authors flag HTML's most glaring omission: anchors only do GET, forms only do GET or POST. PUT, PATCH, and DELETE require JavaScript. This is an "obvious shortcoming" that the authors hope the HTML specification will fix — and in the meantime, HTMX patches it by adding hx-put, hx-patch, and hx-delete attributes. The chapter's treatment of this limitation is honest: it's a design flaw, not a feature, and the workaround (JavaScript) is acknowledged as necessary.

"Scripting was and is a native aspect of the original RESTful model of the web, and thus should of course be allowed in a Hypermedia-Driven Application."

Fielding's Code-On-Demand constraint (Section 5.1.7) is the escape hatch: REST allows scripting, provided it extends rather than replaces the hypermedia model. The authors' position is that JavaScript used to augment HTML (add PUT/DELETE methods, add client-side validation, add animations) is RESTful. JavaScript used to replace HTML (SPA frameworks that treat the DOM as a rendering target for a client-side model) is not. This is the theoretical line that HTMX draws, and it's grounded in the original REST dissertation, not just aesthetic preference.

"The beginning of wisdom is to call things by their right names." — Confucius, quoted in the HTML5 Soup appendix

The chapter closes with practical HTML advice: use semantic elements (<article>, <nav>, <section>) when they genuinely fit, but don't force them — sometimes <div> is the right choice. The HTML spec is the authoritative source; everything else is hearsay. This appendix feels appended rather than integrated, but its advice is sound and its brevity is a feature.

Key Themes

#hypermedia #REST #HATEOAS #HTTP #HTML #web-architecture #concept #pattern

Critical Analysis

This chapter is the theoretical backbone that the HTMX ecosystem often skips. Most HTMX advocacy focuses on developer experience (less JavaScript, server-side rendering, simpler deployments). This chapter grounds those practical arguments in Fielding's architectural theory. The claim isn't "HTMX is nicer to write" — it's "HTMX is RESTful in the original, architectural sense, and JSON SPAs are not." Whether that distinction matters in practice is a separate question, but the chapter makes the strongest possible case that it should.

The HTML-vs-JSON comparison is the chapter's killer app. Walking through the same endpoint under three scenarios (active, archived, new-feature) demonstrates the HATEOAS difference more clearly than any abstract explanation could. This is the section to point people at when they ask "why hypermedia?" The comparison is fair — it doesn't strawman JSON APIs, it just shows what each representation communicates and what it requires the client to already know.

The chapter is honest about tradeoffs in a way advocacy rarely is. Fielding's own words are quoted acknowledging the efficiency cost of the uniform interface. The session-cookie violation of statelessness is acknowledged as pragmatic and useful. HTML's method vocabulary limitation is called out as an "obvious shortcoming." Scripting is explicitly permitted. This isn't a purity argument — it's a "know what you're trading" argument.

The practical implications for the wiki's existing pages are direct. How I Use HTMX with Go's dual-mode handler pattern (check HX-Request, return partial or full page) is the self-descriptive messages constraint in practice: the response tells the client what it needs. Progressively Enhanced Forms with HTMX's build-without-JS-first workflow is Code-On-Demand done right: the HTML/HTTP layer works standalone, and HTMX enhances it. The GUS Stack — Go, Unix, SQLite's "HTMX as much as possible" qualifier maps to the chapter's scripting boundary: HTMX for the hypermedia core, JavaScript only when the hypermedia model genuinely can't express the interaction.

What the chapter doesn't address: the agentic development angle. Written before the explosion of AI coding agents, the chapter argues that hypermedia's flexibility benefits human developers by eliminating API versioning and client-server coordination. But in an agentic world, where an LLM can read API documentation and generate client code automatically, does the flexibility premium still matter? The counterargument is that hypermedia's simplicity benefits agents even more than humans — an agent that only needs to generate HTML is more reliable than one that must coordinate client and server code. The GUS Stack article makes this case implicitly; the chapter provides the theoretical vocabulary to make it explicit.

The HTML5 Soup appendix is a non-sequitur that works anyway. It's appended to the chapter with no transition, covering HTML semantic elements and spec-reading discipline. The connection is "here's practical HTML advice now that you understand the theory" — and while the bridge is weak, the advice is sound. The "check the spec" recommendation is especially relevant in an era where agents often generate HTML based on training-data patterns rather than spec compliance.

Sources: raw/components-of-a-hypermedia-system, Components of a Hypermedia System Last updated: 2026-08-08