I'm constantly working to hand-craft, scrape-craft, and auto-generate OpenAPI Specs, and APIs.json files for as many of the top APIs I can. It is something Steve Willmott (@njyx), the CEO of 3Scale always flicks me shit about, saying I shouldn't have to do that--API providers should be doing this! While I agree, I feel like we haven't reached the point where all providers understand the importance of having an up to date OpenAPI Spec available for their API (some even have them, and work to hide them!)
This is something the savvy API providers like SendGrid are doing, rolling around Github, making sure copies of their OpenAPI Specs are up to date.
Thank Elmer, you da man. Now I just need to convince another 2K other API providers of the importance of having up to date machine readable API definitions available, and actively maintain them. Having your definitions up to date, and easy to find increases the chance a developer will load up in the favorite HTTP client like Postman, Postman, PAW, or API Garage.
Its going to happen Steve! I tell you! Some day, all the good API providers will maintain their own API definitions. You should always have an easy to find copy available as part of your API documentation, but you should also search for them on Github, and submit pull requests to keep them up to date. It is like have little machine readable business cards for your API, sitting on the desks of developers, except with this business card allows you to submit a pull request to update.
P.S. While on the subject--PUBLISH AN RSS FEED FOR YOUR BLOG!!! ;-)
