HATEOAS is an acronym coined in the context of RESTful web services. It stands for Hypermedia as the engine of application state. Imagine the client, human or machine, in a conversation with the server.

They take it in turns, the client asks (requests) something of the server, who promptly responds. Of course, a polite client doesn’t ask just anything of the humble server. Rather, in keeping with protocol, the client only follows the leads (links) suggested by the server. Thus, the conversation is advanced by following link after link.

That’s as good as it is, no diplomatic incidents caused by a client stepping out of line. But does it make for a good conversation? Hardly, with a client who only knows how to be polite, but has no idea what he is talking about. Talking about something presupposes semantics, in this case, an agreement about the meaning of following a particular lead (link).

Talking about something becomes a lot easier when you have an idea what the topic is supposed to be. Enter Media Types. Not any old text/plain, application/xml — that’s like talking about the weather, only for machines. You want something with substance, something fitting your own conversational niche:


There, application indicates a “multipurpose” file, not specifically geared towards human consumption. x. indicates that it is an experimental media type, not registered with IANA. If you’ve got more clout, maybe you’ll be able to officially register a vnd. (vendor) or .prs (personal) type. Finally, the +xml suffix says that the media type is based on XML.

Now for the dénouement: That’s it.

No magic RESTful pixie dust. No script for successfully chatting up every server. Nothing. You could use XML Schema or a relative to specify the data contents of the media types you are using. You could even write some nice prose explaining in so many words what lies ahead when someone follows a link with, say, rel="payment". If you fancy arcane arts, you might write pre- and postconditions in OCL.

In summary, HATEOAS doesn’t imbue client software with more intelligence. It inserts a (useful) level of indirection by offering the client a choice of transitions. Thereby achieving two things: The client is ignorant of the concrete URIs associated with transitions; for all it knows they can be different each time. The client doesn’t have to figure out which transitions are applicable, because the server only offers those to begin with.

What it means to effect a particular transition must still be explicitly coded. So, if the client-side workflow stipulates that a payment transaction is to be started at some point, someone, somewhere has to know of the agreement that such a transition is indicated by a link with rel="payment" and write code to look for and follow such a link.

4 thoughts on “Humble HATEOAS

  1. Good post. Two comments: 1) Instead of inventing new media types, one can invent new link relations in existing formats. 2) Forms are another way hypermedia is used – and in fact they’re far more interesting for complex interactions. I’m not aware of anybody who has explored this in detail (Mark Baker once started with RDFforms, but that didn’t go anywhere AFAIK).

  2. re 1) Do link relations crosscut media types? I understand you as saying that they do. However, then link relations, too, have to be defined in some way and they need to be pointed out to the client. Something like

    Content-Type: application/mymediatype+mylinkrelations+xml

    I’m not against the general idea, but I’m not sure what it would look like in practice.

    re 2) Forms are probably great if you’re using an XML-based media type. Lately, I’ve been using JSON, not XML, and AFAIK there is no equivalent to forms for JSON. As I needed parameterized queries, I resorted to (a simplified variant of JSON Query). Thus, I’m guilty of pasting together URLs, but I reckon it’s only half bad because I use a generic formalism.

  3. I absolutely agree with you that the links themselves have no meaning. There definitely has to be some contextual information related to the link that the “client” of a REST service needs to understand in order to perform a conversation.

    The same problem exists in HTML pages, which are also REST services. In HTML, the implicit assumption is that a living being is reading the page. In that context, there’s usually an excellent evolving REST conversation.

    The reason I’m bringing HTML into the picture is because HATEOAS wasn’t coined in the context of “RESTful web services.” It was coined in the context of REST as Roy Fielding understood it in 2000. Roy Fielding’s context was HTML/HTTP/URI that have people as clients. In that context you have a rich set of additional information about a URL that the “client” can understand: readable text, images and other cues.

    The question still remains as to how to “engineer for [conversation] serendipity” in the context of performing tasks using machine-to-machine conversations with REST APIs. How can you add more cues that a machine can understand? I personally find “rel” to be useful, but not expressive enough to define what the link IS; “rel” only describes a relationships between the link and its “parent”. HTML already has better solutions for the needs of programmatic processing: DOM manipulation based on semantic markup of id and class.

    Web sites also employ “Information Architects” whose reponsibility includes assuring that Web sites as a whole meet the needs of every type of system user. Information Architects assure that each type of task has an appropriate path/conversation through the system. REST data services should probably be approached the same way. When publishing an API, one needs to consider the overall notion of guided paths through the functionality.

    I think that we’re at a point where we need a bigger focus on the conversational aspects of REST services. To get there, we probably need better tooling and better “best practices.”

Comments are closed.