Previously, we discussed the value of offering events from your API that can extend the conversation you have with your consumers. Another consideration for extending your API conversation is to add hypermedia and HATEOAS support. Let’s understand more about these concepts and understand the value they bring to our APIs.
What is a Hypermedia API?
A hypermedia API is one driven by self-descriptive links that point to other, related API endpoints. Often, these links point to other resources that are related, e.g. the owner of a project, or to relevant endpoints based on the context of the consumer.
For example, the Github API offers hypermedia links whenever you request the details on a specific user:
GET https://api.github.com/users/launchany
{
"login": "launchany",
"id": 17768866,
"avatar_url": "https://avatars3.githubusercontent.com/u/17768866?v=3",
"gravatar_id": "",
"url": "https://api.github.com/users/launchany",
"html_url": "https://github.com/launchany",
"followers_url": "https://api.github.com/users/launchany/followers",
"following_url": "https://api.github.com/users/launchany/following{/other_user}",
"gists_url": "https://api.github.com/users/launchany/gists{/gist_id}",
...
}
If an API supplies hypermedia links that are context-sensitive and change based on where the user is within the API and what features and functionality are currently available to the consumer, the API is said to apply the HATEOAS constraint. HATEOAS (“Hypermedia As The Engine Of Application State”) is a constraint within REST that originated in Fielding’s dissertation.
How Does Hypermedia Extend the API Conversation?
1. Hypermedia Informs Consumers About What Is Possible
Hypermedia helps connect the dots of your API, making it more like the web. Imagine using your favourite search engine to find some results, only to never click on any of the results. Unfortunately, that is the way we design most of our APIs – without offering the consumer the opportunity to explore the depth of the data and capabilities offered by your API.
APIs with hypermedia extend the conversation of your API by offering runtime discovery of capabilities. They help API consumers realise what is possible – and what isn’t – when using your API.
2. Hypermedia Enables API Evolvability
Not all APIs stay the same forever. APIs are like any other product – they have a product lifecycle that includes growing in maturity over time. Hypermedia links allow the API to evolve over time, exposing new capabilities as they emerge without disrupting existing API consumers.
Note: I didn’t mention anything about hypermedia protecting clients from changing URLs. That’s because preventing clients from having to think or compute URLs is a side effect, not the primary reason to select Hypermedia.
3. Hypermedia Encourages Loosely Coupling
By including hypermedia into resource representations, API designers are free to stop trying to include everything in every API response. API endpoints can focus on doing one thing properly, using hypermedia links to reference other details that may be fetched by API consumers if and when needed. This creates a loose-coupled API by separating out capabilities into separate, yet related, endpoints rather than forcing every piece of data to be included within each response.
Is Hypermedia a Fit For Your API?
Hypermedia is like “Choose Your Own Adventure” for API Consumers, allowing consumers to discover capabilities and drive execution. For all but the most basic of APIs, hypermedia will expand your API into a more dynamic conversation with your API consumers. It also enables your API to evolve and mature over time, by adding new capabilities as needed by your consumers.
