Applying A Little Hypermedia Is Helping Me Tighten Down My API Design And Tell A Better API Story
11 May 2015
I get hypermedia at a high level, but have no real experience designing or deploying a hypermedia API or client. For the longest time I just watched the hypermedia conversation from afar, but in the last year I have spent time learning about the different approaches, but I still have not gone as deep as I'd like. I'm looking to change this over the summer, and begin to add some hypermedia thinking to my own API design.
To get started I've targeted my curation API for the addition of a hypermedia layer, and I'm choosing Siren as my hypermedia format. Siren spoke to me over some of the other approaches, but once I get my bearings I will look at tackling one or two more implementations. As I do with my other work, I'm just looking to share my thoughts in real-time, as I go along.
First, the process is really helping me tight down my API design. This is something I feel going with an API first design approach using Swagger has helped me, but adding the Siren format to the design of my API is taking this to a whole new level. I still have a longs ways to go in crafting the Siren responses for my curation API, but so far the process of defining the entities, actions, and links is really helping me think through the overall API design--leaving very few loose ends.
Second, the actions and links are also helping me really craft a more meaningful workflow around an API resource that I depend each day. This link curation API that I use in my daily, weekly, and monthly monitoring of the API space has an ever evolving workflow associated with it, but ultimately its been something I've kept in my head, or visualizing in the minmium viable (half-assed) clients I have built to help manage my world. This hypermedia learning process is forcing me to think it through, as if I'm telling the workflow to the world.
This feels very much like storytelling on API Evangelist to me. You see I tell stories to work through my ideas, and craft a nevernding stream of evolving ideas, that help me better understand the world of APis, but also share it in a way that my readers can understand along the way. While applying hypermedia principles to my API design, I feel like I'm working through my API resources in much meaningful ways, and I'm not even approaching what some of the popular benefits of hypermedia are, yet.
I still don't what I am doing entirely, but sure enjoying the process.