I enjoy playing with simple, meaningful ways of leaning about APIs. The other day, during the regular monitoring of the API space, I came across a simple dice rolling API, which I decide to map out using Swagger. Shortly after I did this, I saw Mike Amundsen post an ALPS representation of the Dice Rolling API. Around the same time, I then imported my Swagger into my Postman client, and exported a Postman collection.
Once I had the three formats, I sat back to consider what each of these representations mean to me:
- Swagger - A map of the surface area that is dice rolling.
- Postman - A single representation of actions that can be taken--now.
- ALPs - A representations of the what it means to roll the dice.
I am constantly working to evolve how I view the available API formats that are emerging throughout the space. I will be spending more time generating machine readable definitions for APIs in my stack, trying to push these definitions through these valuable filters. I do not think any single approach provides me with a definitive view of the resources I am describing, but at least give me with various lenses to look through, during my journey.
Swagger left me feel like I am mapping out a vast expanse, but alone doesn't do much for me without more tooling to interpret the map. Postman left me feeling like I could do one thing, linked to the surface area I mapped with my Swagger, but was very confined to just that specific instance, within the world I have drawn with Swagger. ALPS left me feeling like I described something meaningful, closer to the actual experience of rolling a dice.
Ultimately I do not see any of the emerging approaches to defining API driven resources as 100% the solution, or in black and white terms as wrong or right. I see Swagger as very much a bridge to a better defined world, while Postman satisfies the more immediate urges that I have, but ALPS...ALPS has the potential to help me internalize, feel, and interact with my digital resources, in a way that is much closer to the real world (not quite, but closer).
