Hypermedia Systems

1. Hypermedia: A Powerful, Underappreciated Architecture

Hypermedia controls are what differentiate hypermedia from other sorts of media.

Beyond documents. Hypermedia is more than just linked documents like HTML pages. It's a system architecture where media contains controls (like links and forms) that allow non-linear interaction and navigation. This goes "beyond" passive consumption, enabling dynamic systems.

System components. A complete hypermedia system involves several parts working together.

• A hypermedia format (HTML, HXML)
• A network protocol (HTTP)
• A server providing a hypermedia API
• A client interpreting the hypermedia (web browser, Hyperview client)
  This integrated system, not just the format, is key to its power.

Modern relevance. Despite its ubiquity on the web, hypermedia as an architectural concept is often overlooked today, especially by developers focused on client-side frameworks. Understanding the full system reveals its potential for building robust, flexible applications.

2. REST Means Hypermedia, Not Just JSON

if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period.

Fielding's definition. Roy Fielding, who coined the term REST, described the architecture of the late 1990s web, which was driven by HTML exchanged over HTTP. A core constraint of REST is the "uniform interface," which includes "Hypermedia As The Engine of Application State" (HATEOAS).

HATEOAS explained. This means the hypermedia response itself (like HTML) should contain all necessary information for the client to understand available actions and transitions.

• HTML links (<a>) and forms (<form>) are hypermedia controls.
• They encode the next possible states (URLs, methods) directly.
• The client (browser) doesn't need prior knowledge of the API structure.

JSON APIs are different. Most modern JSON APIs lack hypermedia controls. They return raw data, requiring the client to know a priori what URLs and methods to call next. This tight coupling makes them Data APIs, not RESTful Hypermedia APIs, despite common industry misuse of the term "REST."

3. Web 1.0 Apps Were Already Hypermedia-Driven

Even today, in a web development world increasingly dominated by large JavaScript-centric front end frameworks, many people choose to use simple vanilla HTML to achieve their application goals and are often perfectly happy with the results.

Simple and powerful. Early web applications, often called "Web 1.0" or "Multi-Page Applications" (MPAs), were built primarily using HTML links and forms. These two hypermedia controls, combined with HTTP, enabled a vast amount of dynamic functionality.

Core mechanics:

• Links (<a>) trigger HTTP GET requests for navigation.
• Forms (<form>) trigger HTTP GET or POST requests for data submission and state changes.
• The server responds with new HTML, replacing the entire page.

RESTful by nature. These applications naturally adhered to REST principles. The browser, as a hypermedia client, simply interpreted the HTML controls to interact with the server. This approach was simple, robust, and highly flexible to server-side changes.

4. SPAs & JSON APIs: A Different Path, Often More Complex

Applications built in this style are not hypermedia-driven: they do not take advantage of the underlying hypermedia system of the web.

Rise of SPAs. The demand for more interactive user experiences led to the popularity of Single Page Applications (SPAs). SPAs use JavaScript to update the UI directly within a single page, avoiding full page reloads.

Shift in architecture. This approach typically involves:

• Building the UI and managing state primarily in client-side JavaScript (e.g., React, Vue).
• Communicating with the server via AJAX calls, usually exchanging JSON data.
• HTML becomes a rendering target, losing its hypermedia function.

Increased complexity. While enabling rich UIs, SPAs often introduce significant complexity.

• Managing client-side state and synchronizing it with the server.
• Implementing client-side routing and rendering logic.
• Dealing with "JavaScript Fatigue" from complex build tools and dependencies.
  This architecture resembles older thick-client models, moving away from the web's native hypermedia system.

5. Htmx: Extending HTML for Modern HDAs

Htmx is a JavaScript library that extends HTML in exactly this manner, and it will be the focus of the next few chapters of this book.

Bridging the gap. Htmx is a small, dependency-free JavaScript library designed to extend HTML as a hypermedia. It allows developers to build modern, interactive user interfaces without abandoning the core hypermedia architecture of the web.

Hypermedia-oriented. Htmx uses JavaScript not to replace, but to augment HTML's capabilities. It addresses limitations of plain HTML by enabling:

• Any element to trigger HTTP requests.
• Any DOM event to trigger requests.
• Access to all HTTP methods (GET, POST, PUT, PATCH, DELETE).
• Updating specific parts of the page (transclusion) instead of full reloads.

Declarative approach. Htmx achieves this through a set of HTML attributes (prefixed with hx-). This keeps the behavior definition close to the HTML element it affects, promoting Locality of Behavior over strict Separation of Concerns.

6. Declarative Attributes Power Htmx Interactions

Htmx extends HTML as a hypermedia, and it is designed to make that extension feel as natural and consistent as possible with existing HTML concepts.

Attribute-driven. Htmx's core functionality is exposed through declarative HTML attributes, mirroring the style of native HTML controls like href and action. This makes htmx feel like a natural extension of the language.

Key attributes:

• hx-get, hx-post, hx-put, hx-patch, hx-delete: Specify the HTTP method and URL for a request triggered by the element.
• hx-trigger: Define which DOM event(s) initiate the request (defaults vary by element).
• hx-target: Specify which element's content will be updated by the response.
• hx-swap: Control how the response content replaces or interacts with the target element's content (e.g., innerHTML, outerHTML, afterbegin).

Simple and powerful. These attributes allow complex interactions like inline updates, active search, and lazy loading with minimal or no imperative JavaScript code. The behavior is defined directly on the element, enhancing readability and maintainability.

7. Leverage HTTP Headers & Events for Dynamic UIs

Htmx takes advantage of this feature of HTTP and adds additional headers and, therefore, additional context to the HTTP requests that it makes.

Enhanced communication. Htmx extends the standard HTTP communication between client and server. It adds specific request headers (e.g., HX-Request, HX-Trigger) to provide context about the AJAX request to the server.

Server-side control. The server can read these headers to:

• Determine if the request is from htmx or a standard browser navigation.
• Conditionally render only partial HTML fragments needed for the update.
• Implement different logic based on the triggering element or event.

Event-driven architecture. Htmx also emits and listens for custom events.

• Htmx triggers events during the request lifecycle (htmx:configRequest, htmx:afterRequest).
• The server can trigger client-side events via the HX-Trigger response header.
• This enables decoupled updates and complex interactions across different elements on the page.

8. Scripting Enhances, Doesn't Replace, Hypermedia

The goal of htmx is not less JavaScript, but less code, more readable and hypermedia-friendly code.

Scripting is allowed. Roy Fielding noted that REST allows for code-on-demand (scripting). In HDAs, scripting is welcome, but it should enhance the hypermedia model, not replace it.

Hypermedia-friendly scripting constraints:

• Main data format exchanged remains hypermedia (HTML/HXML).
• Client-side state outside the DOM is minimized.

Tools for the job. Several scripting options align with this philosophy:

• VanillaJS (plain JavaScript) structured using principles like Locality of Behavior (LoB) and data attributes (RSJS).
• Alpine.js: A library for adding behavior directly in HTML with reactive data binding.
• _hyperscript: A language designed alongside htmx, focused on event-driven DOM manipulation with English-like syntax.

Focus on interaction. Scripting in HDAs is best used for interaction design (animations, local UI logic), while business and presentation logic remain on the server. This keeps the server as the source of truth and simplifies the client.

9. JSON Data APIs Serve Different Needs Than Hypermedia APIs

JSON APIs were a decade away from becoming a common tool in web development: REST was about hypermedia and the 1.0 version of the web.

Different purposes. While a Hypermedia API (like HTML over HTTP) is ideal for interaction with a hypermedia client (like a browser), JSON Data APIs serve different use cases.

Use cases for JSON APIs:

• Mobile applications (especially non-Hyperview).
• Automated scripts and bulk data processing.
• Third-party integrations and data synchronization.

Distinct requirements. JSON APIs typically need:

• Stability and versioning (clients are tightly coupled to the structure).
• Rate limiting and robust authentication mechanisms (often token-based).
• General endpoints serving broad data needs.

Separate evolution. Keeping JSON Data APIs separate from the Hypermedia API allows each to evolve according to its needs. The Hypermedia API can be highly specialized for the application's UI, while the Data API remains stable for diverse programmatic clients.

10. Hypermedia Works for Mobile Too: Introducing Hyperview

Hypermedia is a general concept, and can be applied to all types of platforms and applications.

Mobile challenges. Traditional native mobile development often leads to thick-client architectures with logic spread across client and server, similar to SPAs. This results in complex codebases and API churn issues.

Hypermedia solution. Applying the hypermedia architecture to mobile offers a way out. The server controls the application state, simplifying the client and eliminating API versioning problems.

Hyperview system. Hyperview is a hypermedia system specifically for mobile, consisting of:

• HXML: An XML-based hypermedia format for defining mobile UIs.
• Hyperview client: A native mobile client (React Native) that renders HXML.

Beyond web views. While embedding a web view is simple, it struggles to replicate native mobile UX patterns (navigation, gestures). Hyperview is designed to represent these patterns natively.

11. HXML & Behaviors: Mobile-Native Hypermedia Interactions

HXML was designed to feel familiar to web developers, used to working with HTML.

XML-based format. HXML uses an XML syntax similar to HTML, making it accessible to web developers and compatible with server-side templating. It includes elements for common mobile UI patterns like lists (<list>, <item>) and inputs (<text-field>, <select-single>).

Behaviors for interaction. HXML interactions are defined using <behavior> elements, decoupling triggers and actions.

• trigger: User interaction (e.g., press, longPress, visible, refresh).
• action: Resulting operation (e.g., push, back, replace-inner, append, alert, share).
• href: URL for actions requiring new content.
• target: ID of the element to modify for update actions.

Native patterns. Behaviors enable mobile-specific interactions like:

• Stack-based navigation (push, back, new, close).
• Pull-to-refresh (refresh trigger).
• Infinite scroll (visible trigger, append action).

Extensibility. HXML and the Hyperview client are designed to be extended with custom elements and actions, allowing developers to add unique features without resorting to imperative scripting for core logic.

12. HDAs Maximize Server-Side Strengths & Simplicity

A big advantage of the hypermedia-driven approach is that it makes the server-side environment far more important when building your web application.

Server as the core. In HDAs, the server is the primary engine of application state and presentation logic. This leverages the maturity and power of server-side environments.

Benefits of server-side focus:

• Access to powerful templating engines for rendering HTML/HXML.
• Direct access to the data store for efficient queries and logic.
• Mature tools for code organization (MVC, modules).
• Simplified client logic, reducing client-side complexity.

Efficient development. Building HDAs often leads to:

• Faster initial development due to simpler client code.
• Easier maintenance as logic is centralized.
• Improved performance by optimizing server responses and data access.

Pragmatic choice. While not suitable for every application (e.g., highly dynamic UIs like spreadsheets), the HDA approach, especially with tools like htmx and Hyperview, is a powerful and often simpler alternative to complex SPA architectures for many common application needs.

Last updated: May 11, 2025