Using API Definitions To Help API Providers With Their API Design Roadmap

As I work to create Swagger API definitions for the almost 1000 companies in my API stack, I'm chasing an elusive definition of a complete Swagger definition for any API. Only a small portion of APIs I am defining using Swagger will reach an 80-90% completions status, in reality most will never be complete for reasons that are totally out of my control.

When it comes to crafting API definitions for public APIs, I may be able to get the API definition complete in the sense that it has all the paths, parameters, responses, definitions, and security configurations, but if the API itself is missing pieces--the API definition will always be incomplete (in perpetuity).

As I work to automate the questions I ask of Swagger definitions, helping me get to a more coherent definition of what is a complete Swagger definition, I can't help feel the need to offer API design tips to the API providers I am profiling. Honestly I have never considered myself a high quality API designer, I've been more business than tech, but I can't help pointing out the obvious stuff. 

I am still using my API definition tooling for my own goals around defining the API Stack, but because I'm building it all as APIs, I intend to open it up to others for analyzing their own API definitions, determining how complete they are, and potentially offering up tips on what could be done to improve them. A kind of self-service, API design tip API, that helps with some of the most common elements that are missing from API designs.

In 2015, API definitions are opening up a buffet of services that are courting API providers ranging from mocking and deployment, to monitoring and security. I don't see why API definitions couldn't also allow for professional API designers to help API providers evolve their APIs in a more constructive ways, from the outside-in. Using Swagger or API Blueprint, professional designers could easily provide suggestions for existing API providers and their designs, then give them potential suggestions that they could use in their API design road-map.

Anyhoo, food for thought!