11436 SSO

API Design: Harnessing Hypermedia Types

May 23, 2013

Previously, we explored how to represent actions and metadata in response messages, specifically state transitions that come from a particular resource. Now, we'd like to discuss hypermedia APIs, one of the keys to offering resource representations rich with information and controls, such that information becomes the conduit by which the user obtains choices and selects actions.

What can we learn from hypermedia types?

Much of the thinking around hypermedia focuses on the way messages are designed. For example, Atom/ AtomPub is the one of the first hypermedia types to be used with APIs; it is used with feeds, publishing, articles in a list, and so on. One important idea that AtomPub showed us is to build a protocol around link relations.


<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>My New Collection</title>
  <summary type="text" />
  <content type="application/atom+xml;type=feed"
  <link rel="edit”
    href="http://example.org/my-new-collection.atom" />

In this XHTML example, a standard link relation (<link rel= “edit”) is used to tell the developer or client of this API, where to edit this particular resource. One of the cool things about valid XHTML is that it also valid XML, which means that parsers like it.


<ul class=“search user-list”>
  <li class=“user”>
    <div class="avatar">
      <a href="/users/@kevin"
        <img class=”user-image" src=”/img/avatar.png" />
      <a href=“/users/@kevin” rel=“user messages”>
        <span class=“user-name”>@kevin</span>
        (<span class="user-text">@kevin</span>)

This is an example from a site called rstat.us. They are implementing the ALPS specification, which adds meaning to classes, such as avatars, users, and user-list search to help build a semantic connection.


  “currentlyProcessing”: 14
  “shippedToday”: 20,
  “_links”: {
    “self”: { “href”: “/orders?page=2” },
    “next”: { “href”: “/orders?page=3” },
    “prev”: { “href”: “/orders?page=1” }

HAL is a JSON-based hypermedia type that is suitable for augmenting your existing APIs. If you're currently using a JSON format, adding links to your response is a snap. The link relations of self, next, and previous iterate through orders in a collection. Overall, HAL's main focus is linking; HAL defines a format that contains links, properties, and embedded resources.  


{ “collection”:
    “version”: “1.0”,
    “href”: “http://example.org/friends”,
    “items”: [
      “href”: “http://example.org/friends/kevin”,
      “data”: [
        {“name”: “full-name”, “value”: “Kevin Swiber” }
    “queries”: [
      {“rel”: “search”, “href”: “./search”, “data”: [
        {“name”: “search”, “value”: “” }

Collection+JSON models AtomPub using a JSON-based format, which may make it more palatable. It also allows for extensions. Queries are modeled here but write templates are also available. Overall, the goal of Collection+JSON is to provide fetch/update semantics for simple lists.  


Then, there’s Siren, Kevin’s own brainchild. Siren is a hypermedia specification for representing entities. As HTML is used for visually representing documents on a Web site, Siren is a specification for presenting entities via a Web API. Siren offers structures to communicate information about entities, actions for executing state transitions, and links for client navigation.

  “class”: [“owner”, “vip”],
  “properties”: {
    “name”: “Kevin”
  “entities”: [
      “rel”: [“https://rels.x.io/dog”],
      “href”: “https://api.x.io/dogs/1”
  “actions”: [
       “name”: “adopt”,
       “method”: “POST”,
       “href”: “https://api.x.io/owners/1/dogs”,
       “fields”: [ { “name”: “dog-name”, “type”: “text” } ]
  “links”: [
    { “rel”: [“self”], “href”: “https://api.x.io/owners/1” }

Siren is intended to be a general specification of a generic media type that can be applied to other types that are not inherently hypermedia-powered. The initial implementation is JSON Siren. Other implementations, such as XML Siren, may also be implemented using the Siren specification.

For more information, check out the following links.

To join the conversation around APIs, check out the API-Craft Google Group.

Next: Binary Data, Caching, Transactions, and More

Microservices Done Right

Next Steps


Resources Gallery