In the context of APIs, hypermedia as the engine of application state is one of the core constraints of REST, the guiding light for web application design outlined by Roy Fielding in his pivotal 2000 dissertation. Though this constraint is often not adopted in RESTful API development, hypermedia holds a lot of latent potential if used properly.

But what is hypermedia? Well, in its fundamental form, hypermedia involves interactive content. The World Wide Web itself is an excellent example of hypermedia in action, as users can link to pages and direct further action from subsequent pages. In terms of APIs, hypermedia involves inserting links into each web API response, enabling the client to navigate through the API in more of a flow. Structuring content this way empowers a client to have more information at runtime, supplying it with options to interact with content dynamically.

Hypermedia APIs offer unique ways to control data, link to pertinent information, and orchestrate an advanced authentication flow. But there’s more to it than that — interestingly, since hypermedia APIs are self-descriptive, they could eschew the need for other complex definition procedures. Introducing hypermedia into web APIs could also help empower a semantic web. Below, we’ll explore hypermedia a bit deeper to discover how to apply it to API design in innovative ways.

Your API Is Your API Is Your API

So what does hypermedia enable? Well, hypermedia can allow API clients to explore and understand resources at runtime. Using this insight, clients can identify accessible data and functionality as they progress through an API, taking further action based on the response.

“An API is nothing else but a network of resources connected through unambiguous, meaningful links,” says Tomasz. As nearly anything could be a resource, this opens up the usage of hypermedia in web APIs quite a bit.

It’s also important to clarify that web APIs may have misappropriated REST. “Fielding’s dissertation is not about how to build APIs on top of HTTP but rather about HTTP itself,” reminds Two-Bit History. Though REST instructs on building networks with the HTTP protocol, it’s not necessarily solely for APIs. Knowing this, the concepts behind REST could be applied to describing many things, including resources, representations of resources, or the API itself.

So, what does this look like in practice? Pluskiewicz shared some hypermedia API examples in RDF in JSON-LD format. These documents are connected as linked data, with relationships expressed using a standardized vocabulary.

Data as a Resource

Consider an API that accesses a database of bus registrations. A hypermedia style API could have data represented by a URI, with links to its type and other resources. As an example, Tomasz shares this snippet:

{
  "@context": {
    "bus": "https://bus.name/vocab#",
    "dbo": "https://dbpedia.org/ontology/",
    "schema": "https://schema.org/",
    "skos": "https://www.w3.org/2004/02/skos/core#"
  },
  "@id": "/registration/2016/06/mza-warszawa",
  "@type": "/api/Registration",
  "bus:owner": {
    "@id": "/company/mza-warszawa"
  },
  "bus:vehicle": {
    "skos:prefLabel": "Solaris Urbino 12 CNG",
    "schema:numberOfAxles": 2
  },
  "dbo:number": 4,
  "skos:prefLabel": "Sample registration"
}

Such a hypermedia structure enables the consumer to lookup more details associated with the response to find out more information. This is made easier with unambiguous proper names and a shared vocabulary, says Tomasz.

Class as a Resource

In this structure, a class could also be a resource as well. In the example below, the class is identified by a URI, using shared vocabulary for its description, and it also links to a supertype, as the class hierarchy is represented as a resource too. Any consumer could follow the links of such a resource to figure out much more details about the system.

[
  {
    "@context": {
      "skos": "https://www.w3.org/2004/02/skos/core#",
      "schema": "https://schema.org/",
      "wikidata": "https://www.wikidata.org/entity/"
    },
    "@id": "/company/mza-warszawa",
    "@type": "/api/Owner",
    "skos:prefLabel": "Miejskie Zakłady Autobusowe",
    "schema:location": {
      "@id": "wikidata:Q270"
    }
  },
  {
    "@context": {
      "rdfs": "https://www.w3.org/2000/01/rdf-schema#",
      "schema": "https://schema.org/"
    },
    "@id": "/api/Owner",
    "@type": "rdfs:Class",
    "rdfs:subClassOf": {
      "@id": "schema:Organization"
    }
  }
]

Everything as a Resource?

But it doesn’t end there. “I think that everything should be a resource in an API,” says Tomasz. He goes on to describe how many other things could be represented this way:

• Data model as a resource: Describing the data model as a resource could help build forms for entering data or interactive user interfaces. One vocabulary to assist here is the SHACL Shapes Constraint Language for describing graph data structures.
• Hypermedia as a resource: The API itself can be described as a resource too. One way to do this is using Hydra, a vocabulary for describing APIs with RDF. This sort of self-documentation is similar to OpenAPI but could make the API discoverable at runtime.
• Access control as a resource: The Basic Access Control ontology is another shared vocabulary for describing access control that was proposed by none other than Tim Berners-Lee.

So, what are the benefits of this resource mania? According to Tomasz, increased hypermedia usage affords several advantages — one of which is discoverability. Since clients are not hardcoded against a specific API, they can explore resources as they follow links to understand the big picture of resources and data sets.

This decoupled nature also improves evolvability, as applications can come and go, and multiple applications can consume the same API more easily, describes Tomasz. “With self-describing data, applications do not have to hardcode representation and meaning of the data,” says Tomasz. A hypermedia design fits the Data-Centric Manifesto quite well, which proclaims that “data is self-describing and does not rely on an application for interpretation and meaning.”

Having self-descriptive information within the API could enable smarter clients and provide a higher degree of automation and programmability. For these reasons and more, “everything should be a a resource in an API,” Tomasz reiterates.

Hypermedia Example: Authentication Flow

One specific real-world example of a hypermedia API in action is a modern authentication flow. Authentication has become a complex process, requiring repeated negotiation between the client and authorization server, beckoning a hypermedia-driven approach.

You may think that authentication is relatively simple. Username and passwords are still a popular way to authenticate with web applications, and they are easy for developers to implement. You collect a password on a form, send it to a server, verify it with a database, and authenticate the user if it matches the corresponding fields.

However, in recent years developers have realized that typical passwords are insufficient — they can be phished or easily cracked if they are not strong enough. Thus, engineers have begun to add additional multi-factor security mechanisms using email, SMS, or an Authenticator app. Social logins through Facebook, Github, Twitter, and other sites have also improved user experience and enabled federated logins.

The authentication process continues to evolve with additional steps, security conditionalities, and new standards for specific industries. “At some point, auth stopped being a simple action … it started to be a complex flow through which the user has to go,” explains Michał. Nowadays, login is a step-by-step process driven by an authentication server that determines the following steps based on the previous input.

For example, a user might first fill out their username then be redirected to a password form. There may be filters to spot suspicious behavior, such as geographical or temporal anomalies. Some users may also have different authentication requirements based on their status. Or, the risk factor of a unique login could trigger verification methods, like a Google captcha.

With so many potential variables on the backend, authentication must now essentially act as a complex state machine. The user flows through each step, and the authentication server responds according to the unique situation at hand. A Hypermedia Authentication API is a logical way to orchestrate these flows. Using hypermedia, the server can respond smartly at runtime and deliver the appropriate UI and actions to move a user to the next step. “A true auth API needs to implement hypermedia,” says Michał.

Evolving Hypermedia

Hypermedia can enable applications that consume APIs to explore and understand resources at runtime. This can allow clients to identify accessible data and functionality as they progress through an API, taking further action based on the response. Hypermedia is helpful in many ways — explicitly in linking data and driving a complex authentication flow.

According to our speakers, the investment in hypermedia takes more effort, but it really pays off, especially when it’s hard to encourage upgrades or when you have mobile clients consuming APIs. It can also help push new features without breaking clients. Lastly, for you true RESTafarians out there, hypermedia is necessary if you aim to build a true REST state machine.