Hypermedia APIs: What are they and what can they do for you?

Like anything in life, APIs come in different “flavors.” In the case of APIs, these are called “API Styles,” and there are five major styles in the API space. Many of today’s APIs use the resource style, and this can be easily verified by the popularity of OpenAPI, which is the most popular way of describing resource-oriented APIs.

But there is a relatively easy way to “level up” from that style by using the hypermedia style. Hypermedia is the style of the Web: It centers around resources (just like the resource style) but also centers around interlinking these resources in ways that are meaningful for consumers.

On the Web, good navigation is essential for usability and user experience, and the same is true for hypermedia APIs: They should focus on making interactions with the API as easy as possible by providing links that take API consumers across the resources of an API in the most useful way to get something done.

This directly leads us to the observation that hypermedia APIs are especially useful when there is the notion of a process or a workflow. If consumers of an API need to have more interactions than just one, then hypermedia can be a very effective way of making it easier to follow these paths. This naturally hints at process/workflow APIs being more conducive to hypermedia APIs than pure data access.

But even for data-oriented APIs, there often are useful ways in which data exploration can be framed as a hypermedia-based path through a dataset. All of this means that considering hypermedia may be a good idea, simply as a way to improve the developer experience (DX) of your APIs. And some major APIs such as GitHub and parts of Amazon Web Services (AWS) are indeed using the hypermedia style.

Finally, it also is very interesting to think about hypermedia across APIs: In the same way as on the Web you don’t care too much whether you’re moving from one server to another, hypermedia APIs can provide the same seamless journey across APIs by using links that are “inter-API” links instead of “intra-API links.”

In API landscapes, this design pattern can become very powerful because it allows consumers to abstract from “I have to use those 13 APIs to get something done,” and instead allows them to focus on “I have to do the following sequence of steps to get something done.”

All of these things point to the fact that hypermedia is an interesting style to consider and explore. With OpenAPI not providing any meaningful support for hypermedia, maybe that’s a bit of an uphill battle in the current technology space, but it’s at least worth thinking about what would be the possible upsides of using hypermedia.

If you’re interested in a “What Would the Web Do?” conversation about this topic, why don’t do join Mike Amundsen and Erik Wilde as they discuss how hypermedia can be a useful pattern for APIs?