I continued to automate the way I profile APIs while profiling the FactSet API this last week. I have been manually creating APIs.json overlays for the APIs.json, as well as OpenAPI so that I can continue to polish indexes for APIs while maintaining the original state of the OpenAPI provided by API producers. I need to enhance the names, summaries, descriptions, and tags for the APIs I am profiling while leaving the original APIs.json or OpenAPI intact so I can apply a rating to them while simultaneously preparing them for inclusion in the APIs.io search engine.
While profiling the FactSet API I produced an APIs.json index of their operations, and harvested all the OpenAPIs that FactSet provides, adding them as properties for each API I index using APIs.json, alongside the documentation, SDKs, and change log FactSet provides. I treat this as the base APIs.json index which should be created by each API producer, but in the absence of this, I am doing it as a representative of APIs.json. My artisanal APIs work is under the APIs.json GitHub organization. However, once I have the base of the index for each provider done, I also layer on what I consider to be two other vendor overlays, one for polishing names, summaries, descriptions, and tags for APIs.io, and a second for applying an API rating from API Evangelist. I’ve talked about this before, but now I want to continue beating the drum about how it will take a village of vendors to raise an API to maturity.
Even if API producers maintain their own APIs.json, OpenAPI, and other machine-readable artifacts, they are still going to need help doing much of the work to deliver APIs at scale across their operations. Search API providers like APIs.io can come in and help make your APIs more discoverable. Ratings providers like API Evangelist can come in and apply ratings to APIs and their operations. I was getting ready to answer the question about whether or not I should define, index and standardize the authorization and authentication across all of the APIs I am profiling as part of my artisanal API work, and I stopped short and declared—-I’ll leave to another vendor to come in and own that slice of this public API pie. I’ll leave monitoring to vendors like API Metrics, SDKs to APIMATIC, and testing, security, and other layers to experts in those areas. I am good at two things, discovery and ratings—I will stay in my lane (pun intended), and provide a machine-readable layer for others to come in.
Right now I am shining a light on what is possible for the public APIs I am profiling with my artisanal APIs.json work, but it is something that could be applied to any API with an APIs.json index in a public or private GitHub repository. Exposing APIs.json indexes with OpenAPI and other machine-readable artifacts is how we are going to scale and standardize the things I mentioned the other week which we will need to automate API consumption for artificial intelligence. API producers just can’t do all the work themselves, and even when they do, it won’t meet the high bar needed for inclusion in searching engines like APIs.io, and other services and tooling. This is where vendors can come in and automate the delivery of API lifecycle services like documentation, monetization, SDKs, monitoring, testing, security, and other things needed to stabilize and scale the delivery of reliable API across thousands of public and private APIs.
As I see it, it will take up to ten properties for each API to harden and mature it for production with each change. Some of these things can be provided as common properties across all APIs, but things like SDKs, ratings, status, change log, and other layers contribute to the overall maturity of an API when they exist. APIs.json provides an index for you to hang these on an API, either as properties when done by the API producer, or as overlays when delivered by a 3rd party vendor. We have a lot of work to do when it comes to convincing API providers to use APIs.json, but having been part of the adoption of Swagger and then OpenAPI, I know what it takes. I’m pretty convinced that I can demonstrate the value of APIs.json with my artisanal APIs.json work, while also introducing the usage of APIs.json overlays to encourage API service providers to help contribute to the maturity of an API. It will all take pushing the artisanal APIs.json work to a critical mass, while bringing API producers and API service providers along for the ride.
