Could AI Bring About a Hypermedia Renaissance?

Over the past decade or so, as APIs have moved toward JSON as the de facto standard format, some developers and architects attempted to bring hypermedia concepts along for the ride – embedding links and controls directly in JSON responses rather than just returning raw data and IDs.

This approach, while theoretically elegant, never really took off in practice. The reason is simple: hypermedia controls require a human in the loop to understand their meaning and context. A developer reading an API response needs to understand what /users/{id}/activate/ actually does before they can sensibly use it. The promise of “self-describing” APIs remained largely unfulfilled.

But with the rise of Large Language Models (LLMs), we may be on the cusp of a hypermedia renaissance – albeit in a very different form than originally envisioned.

Back to Basics

Here’s the key insight: LLMs are extremely good at understanding plain text descriptions and following instructions. They don’t need specialized formats or machine-readable schemas. In fact, they work best when information is presented in a clear, conversational way – much like how you’d explain an API to another human.

This suggests an intriguing possibility: what if we exposed APIs as simple text documents that describe available actions in natural language, with controls expressed as straightforward URLs or HTML-style forms?

For example, instead of:

				
					json
{
  "user": {
    "id": 123,
    "status": "pending",
    "_links": {
      "activate": "/api/users/123/activate"
    }
  }
}

We could have:

				
					Current user (ID: 123) is pending activation.
Available actions:
- List user's groups: GET /api/users/123/groups/
- Activate user: POST /api/users/123/activate/
- Update details: POST /api/users/123/ (accepts name, email)

Why This Makes Sense

This approach has several compelling advantages:

It’s incredibly simple to implement. Engineers can focus on clearly describing their API’s capabilities without worrying about specialised formats or schemas.
The documentation IS the API. There’s no separation between human-readable docs and machine-readable specifications.
LLMs can easily parse the text, understand the context, and make informed decisions about which actions to take.
The format is inherently extensible. You can document new capabilities just by describing them in plain text.

Building for LLMs

Perhaps most importantly, this approach aligns perfectly with how we’ll likely build systems that interact with LLM agents. These agents don’t need pretty interfaces or carefully designed JSON structures. They just need clear, unambiguous information about what actions are available and how to invoke them.

For engineers, this is liberating. We can focus entirely on the functional aspects of our APIs without getting bogged down in design decisions or format specifications. The LLM will handle the interpretation layer, bridging the gap between human intent and machine action.

Looking Forward

As we continue to explore the possibilities of agentic AI-driven automation, this kind of text-based hypermedia could become an important pattern for building interfaces that are both human-readable and machine-actionable. It’s a return to the original vision of hypermedia: not as a complex technical specification, but as a simple, natural way to describe and navigate digital spaces.

The irony isn’t lost on us: after years of trying to make APIs more machine-readable, we might find that the best way to talk to our new AI helpers is to make them more human-readable instead.

If you’re building systems that will need to interact with LLM agents, consider this approach. Sometimes the simplest solutions are the most effective – and in this case, plain text might just be the perfect format for the AI age.