{"API Evangelist"}

My Brain Dump On An API Definition Fueled Life Cycle

I’ve written about this topic before, in an effort to understand the possible incentives for API providers to generate their own machine readable API definitions in formats like Swagger and API Blueprint. These machine readable definitions for APIs and microservices are important to have, but not everyone produces them by default for their APIs, and honestly nobody is going to create them until there are enough incentives to sweeten the pot.

It helps me to walk through this story again, understand the incentives for generating API definitions to date, in hopes of better understanding where we are going. Early on Wordnik developed Swagger, to generate:

Then Apiary came along and moved the needle back, making API definitions more about API design than just API management and integration, with the introduction of API Blueprint, with:

Now we are seeing other providers like Apimatic, Ardoq, and others step up to continue expanding what you can do with machine readable API definitions. I wanted to take a moment to brainstorm everything I am seeing, and would like to see emerge along the API life cycle, that could be driven by Swagger and API Blueprint API definitions.

This is just a brain dump, of of possible ideas that could be developed and generated using machine readable API definitions. Some of it represents patterns I’m already seeing, while some of it represents existing API driven areas, that haven’t been touched by API definitions, but should be (aka opportunity). Swagger and API Blueprint provide a common language for communicating around the central truth that is the API definition, and the more tooling that is developed around these common language, the more incentives there are for API providers and consumers to use them.

I believe we are reaching a tipping point with the tooling that already exists. Interactive documentation, and client and server side code generation is already proving to be enough of an incentive for many, but if you bring in the API design benefits from platforms like Apiary and Restlet, the search discovery benefit introduced by APIs.json and Apis.io, the IDE discovery brought to the table by Codenvy, and visualization tools I’m seeing from Ardok, and now Swagger.ed—things really look like they are tipping. Now I am looking to organize the current tools that are available, and better educate API providers and consumers that they exist, while also looking to stimulate the next wave of API lifecycle tooling that is driven by API definitions.

API Blueprint recently took a big step forward by embracing hypermedia, bringing actions into the API definition layer. In my opinion, all of this tooling is beginning to go beyond just the API meta layer, and permeating potentially every aspect of the API life cycle, and beginning to add more value to the data, content, and other digital resources being made available via APIs. The big picture benefits of API definitions are really coming into focus for me, but there is still so much work to be done, when it comes to properly defining the current API landscape, let alone keeping eye on what is just over the horizon.