One of the greatest ways to improve and sustain an API userbase is by enhancing developer experience. A way to do this is by improving the usability of an API with hypermedia — a method of interacting with APIs. But what exactly is hypermedia, why is it important, and how will it affect an API program? Read on to see why integration and support of hypermedia can be a great boost to your APIs.

What is Hypermedia?

Click to enlarge

By definition, hypermedia is relatively simple — hypermedia derives from hypertext, an extension for plaintext that links to given resources. For instance, when you navigate to a news story or click a link to download an eBook, you are clicking on an element of hypertext.

Hypermedia is the next step in this progression, linking audio, video, hyperlinks, and plain-form data in a non-linear format to other sources of information or data. This is separate from media, which is simply the non-interactive form of hypermedia, and truly makes data extensible in a way that otherwise could not be achieved.

To understand hypermedia, imagine a successful science fiction series. Text is simply the book upon which the franchise is based. Hypertext is a book set, each leading to each other in an effort to make a more connected series. Multimedia is this book series turned into movies; entertaining, but entirely non-interactive. Hypermedia is the video game based upon the book and the media, containing copies of all the previous material, linking in a tangible way various multimedia sources to create a powerful and cohesive experience.

In terms of how an API functions, hypermedia creates tangible links between multimedia and relevant resources. In media, you might see a picture or video as a supporting link to a hypertext or plaintext source. In hypermedia, you’d click that picture or video to navigate to additional relevant sources generated based on the subject at hand.

In this sort of system, the material is present in a stateful system, allowing for logic and machine learning, predictive advertising, visualization of data for the user, and more. This extensibility is what makes hypermedia so very powerful.

How Does Hypermedia Affect APIs

Hypermedia changes the relationship between resources in a fundamental way. Non-hypermedia creates endpoints between resources in a one-to-one method — that is, a resource links to a single static resource, which links back, and by doing this, codes to endpoints to create a network of resources. While this functions well enough for static, unchanging resources, it doesn’t do anything for the user in terms of extensibility or discovery.

Enter hypermedia. Hypermedia fundamentally codes to relationships, rather than endpoints, which creates a huge mesh of networked resources that can be tapped in relative to the original request. This is starkly different from the singular, “if this then do this” relationship of standard media or hypertext APIs.

Imagine going to get that science fiction franchise book mentioned earlier. You walk into a library, and request the specific book — the librarian then hands you the copy, and you go on your way. This is an example an API without hypermedia support — you get what you requested, and nothing else, with a one to one relationship between the request and the resource.

Imagine the same situation, but this time, the librarian not only gives you the copy of the book you requested, but provides suggestions for other books in that genre, Dewey catalogue numbers for other books in the series, a book which gives author information, and images of the author.

That is an example of hypermedia. Hypermedia APIs return results based on their relation to the original resource rather than a simple, single, direct link to said resource. An added benefit of this approach is the fact that multiple, small microservices, the backbone of many APIs, can be tied into a single, unified API, as relational coding can support multiple different queries and functions with far less overhead than traditional static coded APIs.

Why Hypermedia?

Hypermedia is incredibly powerful. One of its main selling points, however, is often the reason hypermedia is ignored — for many, such a system seems too verbose, and too complex. Why use it all, instead of coding a complex internal mesh of endpoints?

To explain why, consider the development of a music service API. Our goal is simple — to develop a music service API that provides data on relevant bands, including music descriptions, the ability to browse related artists, the ability to purchase and download the music, and the ability to share links on social media sites.

The issue is, of course, how we want to go about doing this. On one hand, we could very easily create a direct hardcore endpoint in our code, directly calling a specific URL for a very specific call. This would certainly give us what we want, but only in a very limited way.

If, however, we code this as a relationship with additional arguments, we can call up a variety of data given a simple request:

{
    "@context": {
        "name": "https://music.org/name",
        "alternateName": "https://music.org/alternateName",
        "image": {
            "@id": "https://music.org/image",
            "@type": "@id"
        },
        "related": {
            "@container": "@set"
         }
    },
    "@id": "https://music.org/player/Suiyoubi_no_Campanella",
    "playerId": "1234567890",
    "name": "Suiyoubi_no_Campanella",
    "alternateName": "祝福のカンパネラ",
    "image": "https://music.org/player/Suiyoubi_no_Campanella/avatar.png",
    "related": [ 
        {
            "@id": "https://music.org/player/DAOKA"
        },
        {
            "@id": "https://music.org/player/Kyrary_Pamyu_Pamyu"
        }
    ]
}
“

The beauty of this sort of system is that the properties can be organized in such a way as to be inherited. If this was simply coded as a hard point without the related “id”s attached to them, we would simply get the artist name, an alternative language name, and the avatar image.

By coding relationally, however, when this result appears, we can also code it to present the additional properties as related artists — i.e., artists similar to DAOKA, which is similar to Suiyoubi no Campanella, can be presented as also being somewhat similar to Suiyoubi no Campanella. Likewise, our music service API would make relations between The Beatles and The Who, where The Who is related to The Beatles tangentially through their relation to a third entity, The Rolling Stones. The possibilities are endless.

This is what makes hypermedia so incredibly powerful — it makes a system evolve from a static one to one relationship, and makes a truly dynamic, adaptive product.

Furthermore, if you look at the above example, you’ll notice something interesting — our naming convention was of our own choice. Hypermedia API development allows for naming convention choices for URIs that are unique to the API; furthermore, because it changes how the data is handled, how new relationships between data are established, and allows for updating URIs which can propagate more effectively, relational coding establishes a much more functional and useful API.

The best part about it all? This is a low-level change in thinking and coding style. This means that all the previous security and analytic implementations API developers have come to know and love are compatible and effective — all you have to do is change your mindset.

Popular Hypermedia API Examples

We can see hypermedia in action in a variety of API implementations. As you would expect, the bulk of these implementations are relational at their core.

Family Search API

One of the most well-known and effective relational hypermedia APIs is FamilySearch. When dealing with family genealogy databases, forming relational links between disparate sources of data is the most important and effective means of generating information from a deluge of otherwise unlinked data.

For instance, let’s assume you have 100 users utilizing a genealogy API. Each of those 100 geneologists has done an amazing amount of work, but without linking their data to other users and other sources of data, that content is limited in discoverability and usability.

By linking the already existent data to further, relevant data, you create a system in which relevant data is not only directly linked to each source, but innately discoverable by additional users. You end up with a sort of “force multiplier” for your users — even though your userbase is 100 researchers strong, by linking relational and referential material together, you end up with a userbase simulating thousands of researchers.

Wurl API

For another example of the power of hypermedia, let’s look at Wurl, a video service used by some of the largest media providers in the world. The Wurl hypermedia API handles a lot of what you would expect to be handled by a classic media API — calling video when requested, adjusting bitrate and resolution, etc.

What makes it truly unique, however, are the features packed into the classic API structure. By integrating on-demand streaming with relevance rating, recommendations, rating systems, and so forth, a community is created out of what is fundamentally a solo endeavor.

More important is the way Wurl handles streaming, user engagement, and retention. Content in Wurl is streamed from a pool of media providers — that is, content is not centralized, but distributed from various servers. Because of this, streaming is pulled from the best path possible given the subscriptions the user has active. And because the data is coded in a relational way, relevant titles can be shown, driving cross-purchases, advertising, and more — all of which would be difficult in a static system.

Elastic Path API

Finally, let’s take a look at Elastic Path. Elastic Path is unique as an eCommerce API in that it focuses less on new purchases, and more on the retaining of previous purchases through client discovery, behavior analysis, and consumption analysis. By tracking the behavior of purchasers and attaching relevant data to the results, those who utilize Elastic Path get a better insight into their customers and new opportunities for sales. In the API space, analytics is king, and having such a system in place makes the potential for business growth explosively huge.

Implementing Hypermedia

When it comes to actually implementing hypermedia in an API, modern developers have the world at their fingertips. The industry has spent a lot of time, effort, and money developing hypermedia types, and accordingly, there is a wide range of media types to choose from.

While a standards-based approach is the one we’ll be covering here, the development of one’s own handling of hypermedia types is entirely possible given the feature-rich toolkits and languages of the modern API industry.

Given the time and expense required, however, a standards-based approach is most often the best approach for a developer to undertake. Media types such as HAL, Collection+JSON, and Atom/AtomPub support a wide range of functionalities, and in tidy packages to boot.

For instance, Atom/AtomPub can easily be integrated to support relational resourcing with a simple entry:

	
	urn:uuid:4786d496-4b39-4ab0-ba0d-45b6628e676a
	
	   Kristopher Sandoval

This simple entry establishes a relational link between the atom feed and the resource it feeds from, allowing developers to tie into the edit function without it being defined per hardcoded endpoint.

That’s an RSS solution, however — what about handling preformed responses? Hypermedia support can be included with a simple HAL class, embedding and linking resources together:

{
 “currentOrder”: 5
 “canceledOrder”: 1
 “_links”: {
    “self”: { “href”: “/orderdb?page=5” },
    “next”: { “href”: “/orderdb?page=6” },
    “prev”: { “href”: “/orderdb?page=4” }
  }
}

Additionally, emerging hypermedia types continue to evolve the industry in ways that only highlight the strengths of hypermedia, while nullifying much of its negatives. Siren, for instance, has lent the support of some pretty high-end functionality through its use of actions and action fields, removing the need for hardcoded link relations to requests:

{
  "name": "add-item",
  "title": "Add Item",
  "method": "POST",
  "href": "https://api.x.io/orders/42/items",
  "type": "application/x-www-form-urlencoded",
  "fields": [
	{ "name": "orderNumber", "type": "hidden", "value": "42" },
	{ "name": "productCode", "type": "text" },
	{ "name": "quantity", "type": "number" }
  ]
}

Conclusion: Future Hypermedia Ubiquity

The simple fact of the matter is that hypermedia is the future of the API space, just as media was the future of the World Wide Web, and hypertext the foundation of the Internet itself. While the technology and methodologies inherent to hypermedia are relatively new relative to the industry, they are growing explosively.

In no uncertain terms, hypermedia is a must-adopt for modern APIs. The relational coding, the additional functionality inherent to the design specifications, and the opportunities opened by proper implementation make not adopting hypermedia a costly mistake.