Telling a More Complete Story With Hypermedia
Telling a More Complete Story With Hypermedia
How can you use hypermedia to document your APIs — and should you even being so in the first place? We need to educate API consumers.
Join the DZone community and get the full member experience.
Join For FreeThe Future of Enterprise Integration: Learn how organizations are re-architecting their integration strategy with data-driven app integration for true digital transformation.
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.
Make your mark on the industry’s leading annual report. Fill out the State of API Integration 2019 Survey and receive $25 to the Cloud Elements store.
Like This Article? Read More From DZone
Published at DZone with permission of Kin Lane , DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.
{{ parent.title || parent.header.title}}
{{ parent.tldr }}
{{ parent.linkDescription }}
{{ parent.urlSource.name }}