Notes

Hypermedia APIs

3 min read

Hypermedia apis

The problem

We needed to present a set of actions to the user, but only the actions they have permission to take. The frontend needed logic to show or hide actions based on permissions, but the backend also needed that logic because we had to account for savvy users modifying the code in their browser. This led to duplicated logic that needed to constantly be kept in sync across multiple systems.

The other thing we noticed was the lack of standardization on how the APIs were structured. Even when sticking to the REST standard, there was a wide range of different possible structures for the API to take. This led to every company with an API, and sometimes each team within that company, developing their own API format. For example, it would be difficult to navigate Twitter’s API without relying on published documentation. If you then wanted to navigate Reddit’s API, you would need to read a whole new documentation.

JSON has no built-in support for hyperlinks, which are a fundamental building block on the Web.

Benefits

  • Provides a universal standard for APIs, the same way HTML is the universal standard for web content
  • Clients can navigate the API with much less client-side logic
  • Direct parity with HTML makes it easy for the frontend to render
  • Entities have unique self links which allows parallel fetching and easy browser-side caching
  • Allowed API actions are provided with the response data

For example, calling http://example.org/customers/123 might include this in its response, indicating how the frontend can update the customer entity:

"actions": [
  {
    "name":"update-customer",
    "title":"Update Customer",
    "method":"POST",
    "href":"http://example.org/customers/123",
    "type":"application/x-www-form-urlencoded",
    "fields": [
      {"name":"status","type":"hidden","value":"partial"},
      {"name":"return","type":"hidden","value":"full"},
      {"name":"email","type":"text" },
      {"name":"sms","type":"number" }
    ]
  }
]

Definitions

  • Hypermedia: an extension of the term hypertext (as in HTTP or HTML), is a nonlinear medium of information that includes graphics, audio, video, plain text and hyperlinks. This designation contrasts with the broader term multimedia, which may include non-interactive linear presentations as well as hypermedia.
  • HATEOAS: Hypermedia As The Engine Of Application State—basically REST with Hypermedia
  • Siren: Structured Interface for Representing ENtities—The specific format of json used for hypermedia responses

Understanding the term hypermedia

Where a hyper-cube is a cube within a cube, and hyper-text is text within text (via links), hyper-media is media within media. In practice this just means hypertext with any content type. Hypermedia and hypertext are so similar in principle that they are sometimes used interchangeably.

When people talk about hypermedia APIs they’re usually talking about APIs returning links to more APIs, and the available links changing based on the state of the object and permissions and such, which is technically actually HATEOAS, but people just say “hypermedia” cause that’s close enough.

The term “hypermedia” itself is very old, first used in 1963. The web is already an example of hypermedia standards, for example a browser can render a YouTube video just as easily as a news article.

References:

Graph View