Telling a More Complete Story With Hypermedia

I spend a lot of time connecting the dots with APIs, trying to understand what resources are available via an API and how I can actually put them to use. I can usually land the documentation page of an API, be up-to-speed about what resources are available, and have a basic level of understanding of how I can put the APIs to work withing 15 minutes — that is, if the API is reasonably designed and somewhat documented.

Where things get tougher for me and require much heavier of a cognitive load is going from the basics to understanding what is possible when you can really connect the dots between all the APIs a provider makes available.

While I was profiling and learning more about the AWS API Gateway, which is an API that lets you deploy and manage your APIs, I found that their usage of the hypermedia format HAL significantly contributed to me going from basics to a better understanding the big picture and what is possible at scale. Each API path I learned about gave me a wealth of links describing what was possible next, providing details on what I should be doing next, perpetually introducing and teaching me about what is possible with the AWS API Gateway.

I am hyper aware of the cost of getting up and running using an API. As a one-person shop, reviewing thousands of APIs, my time is precious. I've looked at all of the AWS APIs, and it's easy to get a basic understanding of the resources available with their classic action approach, but I rarely ever see the big picture of what is possible with the API. After spending the same amount of time in the AWS Gateway API (as I would have spent learning any of the other AWS APIs), I found that I had a much greater understanding of what was possible due to the presence of the hypermedia design pattern.

Hypermedia provides a much more complete story for me, as well as offers a much more honest approach to supporting the API. It doesn't just provide me with documentation of available API resources; it connects the dots for me, showing me what is possible. In this scenario, it is an API deployment and management API, so while I'm learning about the API, I'm also being introduced to new API deployment and management concepts along the way.

We shouldn't assume that all of our consumers will be able to connect the dots. We should be providing them with a complete story of what is possible with the API design patterns we choose.