DZone
Integration Zone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
  • Refcardz
  • Trend Reports
  • Webinars
  • Zones
  • |
    • Agile
    • AI
    • Big Data
    • Cloud
    • Database
    • DevOps
    • Integration
    • IoT
    • Java
    • Microservices
    • Open Source
    • Performance
    • Security
    • Web Dev
DZone > Integration Zone > 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.

Kin Lane user avatar by
Kin Lane
·
Mar. 19, 17 · Integration Zone · Opinion
Like (2)
Save
Tweet
2.83K Views

Join the DZone community and get the full member experience.

Join For Free

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.

API Hypermedia

Published at DZone with permission of Kin Lane, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Popular on DZone

  • The Power of Enum: Make Your Code More Readable and Efficient [Video]
  • Biometric Authentication: Best Practices
  • Build a Data Pipeline on AWS With Kafka, Kafka Connect, and DynamoDB
  • Exhaustive JUNIT5 Testing with Combinations, Permutations, and Products

Comments

Integration Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • MVB Program
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com
  • +1 (919) 678-0300

Let's be friends:

DZone.com is powered by 

AnswerHub logo