REST and Hypermedia

In the space of HTTP-based APIs, there are a few main architectural styles. One of these is REST (REpresentational State Transfer).

There are a variety of APIs across the internet that adhere to parts of the RESTful constraints, but adhering to all of them is relatively rare.

This document does not aim to explain REST, only to give an overview of one of the prominent features - HATEOAS (Hypermedia As The Engine Of Application State).

One of the main conceptual shifts is talking about “resources” rather than “routes” or “URLs”. When fetched, each resource returns a set of hypermedia links. Each link represents a relationship to another resource. For example, an Equipment resource has a link relation to a Position resource that represents current location of that Equipment.

Unlike systems expressed in an OpenAPI specification, a hypermedia-driven API never requires the client to construct a URL. A client can navigate from resource to resource using only the links it is provided.

Conceptually, this is how a human interacts with a website in a browser - clicking links to move between pages. An automated client only needs to know the “shape” of an API to be able to navigate and discover them.

The Shape of the Equipment API

Every response from this API is either a singular resource or a collection of URIs that refer to singular resources.

All resources follow the same basic structure:

{
  "links": [
    {
      "rel": "self",
      "href": "<URI>"
    }
  ],
  // resource-specific key/values here
}

Every collection response contains the same links section, with an additional items array

{
  "links": [
    {
      "rel": "self",
      "href": "<URI>"
    }
  ],
  "items": [
    {
      "id": "<URI>"
    },
    // ...
  ]
}