Part 1: Hypermedia and HATEOAS

In the previous episode, we gave this definition of HTML as hypermedia:

hypertext = (representation of) information + action controls.

Let's unpack that. Here's how hypermedia works:

client and server exchange hypertext in a request-response cycle;
hypertext is representation of information, bundled up with action controls — which act as affordances for manipulating said representation.

Here's a (rather long) piece of HTML:

<body>
  <h1>Message #<%= @message.id %></h1>
  <h2>Hello World</h2>

  <ul class="details">
    <li>From: joe@example.bar</li>
    <li>Date: June 2, 2024</li>
    <li>Status: Read</li>
  </ul>

  <hr />

  <ul class="actions">
    <li><a href="/messages/42/reply">Reply</a></li>

    <li>
      <form action="/messages/<%= @message.id %>" method="post">
        <input type="hidden" name="_method" value="PATCH">
        <fieldset>
          <legend>Flag as</legend>
          <ul>
            <li>
              <input type="radio" id="priority" name="flag" value="priority" checked />
              <label for="priority">priority</label>
            </li>
            <li>
              <input type="radio" id="spam" name="flag" value="spam" />
              <label for="spam">spam</label>
            </li>
            <li>
              <input type="radio" id="archived" name="flag" value="archived" />
              <label for="archived">archived</label>
            </li>
          </ul>
          <button type="submit">Submit</button>
        </fieldset>
      </form>
    </li>

    <li><a href="/messages/42">Delete</a></li>
  </ul>
</body>

Looking at the above markup, we see some headings; a list of metadata (<ul class="details">); and a list of actions (Reply, Flag, Delete) afforded to the user. This looks like a page for a Message with a particular id; the HTML was rendered as result of the user requesting the resource by visiting the following URL:

GET /messages/42

The user had either clicked the link (an a element) from the list of messages, or navigated directly to the resource page by typing its address (the URL) in the browser address bar.

So this is the hypermedia workflow:

The user enters the application through a single entry point (URL).
The user is served a (hypertext) document with embedded action controls.
The user interacts with an action control to issue a new request to the server.
The server sends back a response, again formatted as hypertext.
The cycle continues until the user quits the application.

This is HATEOAS, an idea that lies at the very core of REST, or Representational State Transfer, and is the original vision behind HTML as an implementation of hypertext.

HATEOAS = Hypermedia as the Engine of Application State.

As per Roy Fielding, writing in 2000:

Distributed hypermedia provides a uniform means of accessing services through the embedding of action controls within the presentation of information retrieved from remote sites.

Source: https://ics.uci.edu/~fielding/pubs/dissertation/introduction.htm

Said another way: at each step, the representation of information comes bundled together with action controls (special hypertext elements) that allow the user to manipulate the hypermedia (by issuing requests for fetching, creating, updating, or deleting new resources on the server).

Every request-response cycle is isolated and has no knowledge of the prevous or the next cycles. It contains all the instructions necessary to operate it to the next step, and thus does not depend on interaction history, server-side state or side channel information to be operable by the user.

Notice that there is a distinct recursive quality to this mechanism:

Hypermedia provides the controls to manipulate hypermedia.

And with that, we are ready to update our defintion of hypermedia:

hypermedia: addressable information resources (text, images, video) that can be:

navigated by non-linear paths (by clicking links embedded in text)

embedded in each other using transclusion (more on this concept later)

created, updated, and deleted using links and forms (also embedded in text).

Buy me a coffee