My API Definitions Are Incomplete But You Do Not Want To Contribute
26 Sep 2016
I am perpetually working to publish all of my API definitions my API Stack Github repository, with the front available as the API Stack. I regularly push the latest copies of all of my OpenAPI Specs to these Github repos when I have time, but my OpenAPI Specs are far from complete, and are something I'm always working to make as complete as a I can, and certify when possible.
My primary objective around defining APIs using OpenAPI Spec is all about API discovery, and understanding the request and response surface area for many of the publicly available APIs out there today. Secondarily I'm interested in actually putting these API definitions to use across the API lifecycle in design, deployment, management, testing, virtualization, and client tools and services.
It takes a lot of work to certify an API definition as complete--a process best executed by the API owner. In the absence of this, I am trying to fill in the gap(s) where I can, but as a one-person operation, I only have so much bandwidth. I have had people ask me if I'd focus on specific APIs they are interested in having, and even have some folks pay me for this work, but what really surprises me is the number of emails, DMs, and Github requests I get from folks telling me about how incomplete they are, and the low number of folks who ever contribute back by sharing their definitions with me.
People really enjoy emailing me to tell me my API definitions are incomplete, but they rarely fork and contribute back any API definitions to my work--even though I regularly ask people if they could (at the very least submit an issue with URL to where it exists on your server). I feel like this is the general tone of the space that has been set by VC investment and unhealthy views of intellectual property defined by companies like Oracle and Google. People are perfectly happy building on the open work other folks do, but very rarely ever give back and share the API definitions that they have in their own collections.
Hypermedia visionaries are often frustrated because people refuse to emulate the best patterns currently available, and that OpenAPI Spec is just a bridge. My concerns are more that we can't even get people to walk across the bridge to greener pastures because the greedy nature of the space is more focused on scrapping and keeping parts and pieces of the bridge for themselves, leaving it as something nobody will walk across. Let alone getting us to the place where we all share and follow a common set of API and schema patterns across all industries.
Please share your API definitions, it doesn't have to be part of my API Stack work, but please make them easily found within your API portal.