An Introduction to Hypermedia APIs

What is hypermedia? 🤔

The concept or term hypermedia isn't new by no means. You might not be familiar with it but it actually dates back to when Roy Fielding made his dissertation about REST in 2000. To sum it up, the idea of having a Web API with hypermedia means that the resource's representation contains links to other resources, enabling the client to navigate the Web API without knowing the URL for that resource, except the API "entry point". With this approach, the client doesn't need to have a lot of logic related to figuring out if the user can have access to a certain operation/action. This logic is moved to the server and it's materialized in links that the client doesn't assume they exist in the API response. But if they do, the client can then transition into another state, like navigating to another web page, or performing an action like "Add product to the cart".

I think a cool exercise to do when starting to build a new Web API is to think what are the resources and what are their relationships. These relationships can then be named and you can build a roadmap that shows the possible paths a client can take to get to a specific resource.

From my experience so far, developing a project with hypermedia in mind is a challenge (maybe more costly on the client side), since you are trying to reach the level 3 defined by the Richardson Maturity Model (RMM). Yet it's one that my team and I accepted, for our final year project in college. I feel that this made me study more about APIs in general and REST (Representational State Transfer).

Advantages

Discoverability

Imagine it's your first day at your new job, and to complete the first task you need to learn how to interact with an external API because your business depends on this 3rd party service for a payments service. If you get links to related resources when you make a request, you can get a sense of what operations are available to you.

Extensibility

You can look at links as a way to extend the capabilities of your Web API as well. Say your business decides they want a new feature like the ability to display an announcement message on the home page. You could implement something like this:

function HomePage({ homeResponse }) {
  return (
    <>
      <h1>Welcome!</h1>
      {homeResponse._links.announcement && 
          <Announcement link={homeResponse._links.announcement} />
      }
    </>
  )
}

The Announcement component would use the link to make an HTTP request to fetch the announcement resource and then render its info.

I think it's quite powerful to be able to have links on the representation of a resource so that the client can easily decide what to render on the UI. Since it's the server who decides what links to return, a feature like "Temporary Product Promotions" could be implemented with a new link, and then after some days the server doesn't provide that link anymore, and the client simply doesn't render that capability anymore. It's like turning a switch on or off 😄.

Trade-offs

While we gain flexibility on our Web API, we now use more bandwidth sending our responses to clients, since the representations in the response are bigger (they can contain links, embedded objects, etc). It's up to us to decide if this inconvenience is worth it or not.

There is also the possibility of you going through all the work of building a hypermedia Web API, but your clients still hard code the URLs to your resources afterwards. This disallows you to change your URLs which is something a hypermedia approach strived for. Making reactive clients that adapt to change is harder and there is a cost of development attached to it. So the decision to build one comes down to trade-offs, and analysing the extra complexity.

Use cases for hypermedia

In my last semester at the ISEL university, I had a class called "Web Application Development". During that semester I was able to read the recommended book "Designing Evolvable Web APIs with ASP.NET", where one of the teachers was a co-author of that book. It talks about how hypermedia can make Web APIs evolve independently from its clients so that when the API does change (which is a common scenario in the web industry) because of new sets of requirements by the business, old clients don't "break" and new clients can take advantage of the new changes.

If you are building a private API, that only has one client, and you are in control of that client app. Then going so far as making you API hypermedia driven, might not be the best use case.
If you are building a public API (e.g. GitHub, Amazon), it could fit your use case since you can have many types of consumers. Just picture today's existing devices: mobile phone, consoles (e.g. PS4, Xbox), PC, Tablet, Smart Watches, Smart TV, etc.

Conclusion

What are my current thoughts about building a hypermedia Web API? Well, I think you should evaluate your scenario and go from there. There are probably APIs that get built simply to be used for a couple of months. There are also cases where the API developer and the client app developer are "sitting next to each other", and the client can be coupled to the API route URLs because they can talk to each other quickly. In these cases, I don't think evolvability and longevity of the API, are the main concern. But when this is a concern and an objective, a hypermedia based Web API can get you far.

Also, I think we should look at this approach as another tool that you can use to build, design and implement APIs for your software systems. Yes there are others like GraphQL, but I believe there is no "one solution" to a problem. Instead, I think there are trade-offs and decisions, and an engineer needs to analyze the needs of the business, to then decide what tool to use since each one brings different characteristics to the system.

If you want to (I recommend and encourage), try building yourself a hypermedia API and a client app tha uses it. For me, it's exciting to learn more about ways of building a system that is prepared to evolve and be extended. I'm still learning about more use cases in the industry and stories (successful or not) of people taking this concept to practice. So if you have an opinion or any resource about this, feel free to share 😄.
Hopefully, you enjoyed reading this post and took something out of it.

Resources

Here are some resources and examples of APIs that are hypermedia based:

• REST APIs must be hypertext-driven
• Spring HATEOAS
• JSON Schema
• Cortex API
• GitHub API
• More examples from Darrel Miller