Hypermedia

Hypermedia is the most intellectually compelling and most commercially frustrating idea in the entire API design world, and I’ve held both of those feelings about it for over a decade. A hypermedia API embeds navigational links and affordances directly in its responses, so that instead of a client needing out-of-band knowledge of every URL and action, the API tells the client what it can do next through the links it returns. This is hypermedia as the engine of application state — HATEOAS — the principle at the top of Roy Fielding’s REST maturity model. I wrote about what a hypermedia API is back in 2014, and the core idea is elegant: the API guides the client through its own structure, the way links on a web page guide a human through a website. Done right, hypermedia produces APIs that are more discoverable, more evolvable, and more loosely coupled. The frustration is that, despite being clearly better in theory, hypermedia never achieved the mainstream adoption its elegance deserved.

The promise of hypermedia is genuine, and I’ve articulated it many times because I believe in it. A hypermedia API produces a more honest and flexible contract, as I wrote in 2016 — the links in the response describe what’s actually possible right now, given the current state and the consumer’s permissions, rather than forcing the consumer to hardcode assumptions about what they can do. This makes the contract looser and more evolvable, as I argued in 2017: because the client follows links rather than hardcoding URLs, the provider can change the underlying structure without breaking clients, as long as the link relations stay stable. Link relation types, which I wrote about in 2017, are the vocabulary of this — the named relationships (“next,” “previous,” “edit,” “payment”) that tell a client what each link means. The media types that carry hypermedia — HAL, Collection+JSON, Siren, JSON-LD, JSON API — each provide a structured way to embed these links and affordances. Hypermedia is, in a real sense, just applying the lessons of the web itself to APIs: the web works because of links, and hypermedia APIs work the same way.

I got deeply involved in the hypermedia community, and that community was one of the best in the API space. The hypermedia panels at API Craft in Detroit in 2014 brought together the people who’d thought hardest about this — Mike Amundsen, Mike Kelly, Steve Klabnik, Markus Lanthaler, Kevin Swiber, Jørn Wildt — and the state of hypermedia discussions those gatherings produced were some of the most intellectually rich conversations I participated in. These were people genuinely trying to figure out how to make APIs work the way the web works, and their thinking shaped how I understood good API design even when the broader market wasn’t listening. The hypermedia community was small, serious, and right about a lot of things, and being part of it deepened my understanding of REST, of links, of affordances, and of what APIs could be if we took the web’s own architecture seriously.

The hard truth, which I came to accept reluctantly, is that hypermedia’s biggest obstacle is cognitive load. I wrote in 2015 that the biggest barrier to hypermedia adoption is the cognitive load of the average API designer — and that’s the honest diagnosis. Hypermedia is harder to understand, harder to design, and harder to consume than simple REST. The average developer wants to make a request to a known URL and get back a predictable response; they don’t want to write a client that navigates links and interprets affordances. The elegance of hypermedia comes at the cost of complexity, and most developers and most organizations chose simplicity. I admitted in 2016 that we underestimated the time it would take for hypermedia to be absorbed — and the deeper truth is that it largely wasn’t absorbed at the level its advocates hoped. The market chose simple, RPC-flavored, URL-based REST over the more correct but more demanding hypermedia approach, the same way it chose Flickr’s pragmatic method-based design over stricter REST.

The pragmatist position is where I landed, and I think it’s the honest one. I asked in 2014 whether you’re a hypermedia pragmatist — and that framing captures my own resolution. You don’t have to go full HATEOAS to benefit from hypermedia ideas. You can add links to your responses, use link headers for pagination, include “next” and “related” links, and adopt the parts of hypermedia that reduce coupling and improve discoverability without imposing the full cognitive burden on your consumers. Applying a little hypermedia, as I wrote, helped me tighten my own API design and tell a better story, even without committing to the whole philosophy. The pragmatic middle — some hypermedia, applied where it genuinely helps — is far more achievable and far more adopted than the purist vision, and it captures much of the value at a fraction of the cost. Hypermedia doesn’t have to be all-or-nothing, and treating it as a spectrum rather than a binary is what makes it usable.

The fascinating recent turn is that hypermedia may finally find its moment with AI agents, which is a vindication I didn’t fully see coming. I wrote in 2025 that where people see AI agents, I see API discovery, semantics, hypermedia, and workflows — because an AI agent navigating an API at runtime is exactly the use case hypermedia was designed for. A human developer doesn’t want to follow links and interpret affordances; they’d rather just read the docs and hardcode the calls. But an agent that needs to discover what’s possible and navigate dynamically benefits enormously from an API that describes its own affordances through hypermedia. The cognitive-load problem that doomed hypermedia for human developers may be exactly the problem that hypermedia solves for machine consumers, who can process the links and affordances tirelessly. After a decade of hypermedia being the right answer to a question most people weren’t asking, the agentic era may finally be asking the question hypermedia was built to answer. The semantics, the link relations, the self-describing affordances — the things the hypermedia community got right in 2014 — are exactly what agents need to navigate APIs autonomously. Hypermedia was perhaps just early, and its moment may be arriving now that the consumers are machines rather than humans.

Guidance

API Learnings

APIs

API Governance

API Solutions

API Discovery

API Building Blocks

API Evangelist LLC

Hypermedia

References

Guidance Details

Explore more

Discover APIs