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:

  application/x.mytopic+xml

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.