Hypertext: A Renewed Push


What was old is new again…

Many things cycle over time. Coke to New Coke to New Old Coke; stairs to escalators to stair machines. Technology, and APIs specifically, are no different. We’ve gone from web services in SOAP with a description language (WSDL), to simple RESTful services just to add back in OpenAPI, RAML, etc. We rediscover things and give them new names. UI Platform APIs (Controllers), capabilities (Feature Driven Design) and the list goes on…

One item that has begun to be rediscovered is one that was never really taken advantage of and talked about more like it was mythology, but now, finally may be considered worth our time.

HATEOAS – What is it?

HATEOAS, or Hypertext As The Engine Of Application State, is the 3rd and final stage of the [Leonard] Richardson Maturity Model (RMM) and deemed by Roy Fielding (the man who gave us the term REST by the way) as a requirement to be an actual REST service.

In its simplest terms, HATEOAS is about discovery. An individual resource is great, but as a consumer, where do I go from there? What actions can be done to this resource? What other resources are linked/related to it? How do I get to those? Let’s look at an example:

Screenshot from 2017-06-07 09-10-25

As you can see above, actions and relations are conveyed through a series of URLs given in the payload associated to some relationship or action names. This allows a consumer to see immediately what they could do next with a given resource and how to get there.

The ultimate goal would be that a consumer could enter into an API with nothing, but the initial URI and a set of media types and be able to traverse the entire system through the given hypertext links.

Why is HATEOAS good?

In the same vein of giving things new names and ways of thinking about old things, if we think of consumer interactions with an API as a conversation, a single resource would be like overhearing just a piece of a conversation.

“If it weren’t for my horse, I never would have made it through that last year of college. – Anonymous”

What?! What could that possibly mean? You need the context to really make sense of it all. HATEOAS is the mechanism that delivers that context to us. It continues or extends, the conversation.

Why is HATEOAS suddenly relevant now?

So why are we suddenly talking about HATEOAS now? Well… to quote one of my favorite movies:


“We marveled at our own magnificence as we gave birth to AI….

A singular consciousness that spawned an entire race of machines. – Morpheus, The Matrix”

Okay, things aren’t all that… yet, but the beginnings of AI and automated bots are all the rage and are not going to slow down anytime soon. Hypertext is the perfect engine for these types of systems to self-discover the capabilities and possibilities of an API and delivers them to their users. In a world where everyone is talking about machine readable descriptions such as OpenAPI and the like, HATEOAS now has an opportunity to be the game changer it was meant to be. James Higginbotham, from LaunchAny, gave a presentation on renewed design considerations in the world of Bots at this year’s Gluecon.


What is it going to take

First, we should get real and dispose of a couple of myths that surround HATEOAS.

  1. “HATEOAS is self-discoverable, we don’t need documentation”
    We’ve all heard this one many times about many things. It’s NEVER true. Sure given the behavior of HATEOAS, theoretically documentation shouldn’t be needed to traverse the API. Developers, customers, and especially your employer are going to want to read the docs. At some point, human readable documentation will be asked for.
  2. “Resource or URL design isn’t needed with hypertext”
    Again, given the behavior of HATEOAS, we shouldn’t need to overly design our routes or endpoints, the links will tell the consumer exactly where to go. HATEOAS clients are not in abundance as of yet, much less the norm. We still want to make things easily traversable by us outmoded humans. I’m also pretty sure that SEO thing is still a thing.

So with those couple items dealt with, the biggest hurdle for HATEOAS (besides getting the developer to use both links and documentation) has generally been the lack of, or adoption of, clients capable of traversing the links. Have no fear though development of such clients is on the rise. The Spring framework has toolsets for this when working in Java, a quick search for HATEOAS client in NPM can get you several options for JavaScript, and when speaking of specific implementations of HATEOAS such as HAL or JSON-LD (We’ll talk implementation patterns in another post) the list grows even more.

Let’s get linking! I personally can’t wait to meet my AI overlords.