Not a single mention of the human element, which I will theorize is the main reason.<p>Psychologically, looking at a formal specification is pretty intimidating. How many people do you know who enjoy sitting down with a cup of coffee/tea and their favorite time-worn leather-bound copy of RFC7231?<p>Most developers I know love getting something to work. They love the feeling of having mastered something to the point that just reading "GET /widgets" is enough for them to go off to curl and implement the rest ad-hoc as they're visually inspecting the JSON and occasionally referring back to the docs.<p>Creating formal specs is probably the most efficient way to go in a purely computational sense, but reading specs is hard work and it's not especially inviting or rewarding, especially to a class of workers that would much rather jump in, get their hands dirty, and figure it out themselves. It's why developers love frameworks/APIs that just <i>feel</i> simple and familiar. The low cognitive overhead, and low barrier to entry gets you into a wonderfully endorphin-driven flow that's hard to replicate.<p>Formal specifications are great. But they won't likely get read by people. And people, not machines, are going to drive your profit as a business offering a shiny API.<p>So should you focus on your formal spec first, or human-readable API documentation? Probably the latter. And good luck convincing the business owners that a spec is a high priority now that you technically have everything covered.
One of the things that striked me when I worked on my first API was that all of service registration, search, payments and certification incur a lot of overhead. Most of these problems are addressed by using third party platforms and middleware (for example Mashape + Kong). But this seems to restrict findability to this one platform and also introduces nontrivial dependencies and fees even for small projects.<p>Therefore, I am trying to find or create systems that do this without this requirement, in a mostly trustless p2p fashion, starting with an extension to the OpenAPI spec:<p><a href="http://i.imgur.com/4mmckZ9.png" rel="nofollow">http://i.imgur.com/4mmckZ9.png</a>
<a href="https://gist.github.com/void4/523f23b50e1572e8ef60" rel="nofollow">https://gist.github.com/void4/523f23b50e1572e8ef60</a><p>I wonder what comes after that. Most probably different transports and patterns of interactions. <a href="http://iris.karalabe.com/" rel="nofollow">http://iris.karalabe.com/</a> might show how it will look like.
I think API owner need to see some value in publishing spec.
And SDK generation, not a strong argument for publishing since it can be done on API owner side with more control and better quality.<p>IMHO key component here is automatic integration, you simply publish a link to your spec and you magically have integration with a number of 3rd-party tools/services.<p>I currently work on catalog which does exactly this, and you can see list of integrations here:
<a href="https://github.com/APIs-guru/api-models#existing-integrations" rel="nofollow">https://github.com/APIs-guru/api-models#existing-integration...</a>
I'm wondering if there's actually a widespread demand/need for public API specs.<p>Contentful's API specification (in the blue print format) has been open for a while as a side effect of opening up our documentation. I'm not aware of any user ever using for anything but the generated documentation (and there have been bugs in the past that would have made things like generated test servers break quite nicely).<p>What (potential) use case am I missing?
A possible reason is the fear of losing intellectual property. Providing a machine readable format makes duplication much easier (although you'd still have to deal with the implementation). The funny part is that the Oracle vs Google API Lawsuit in effect sets a precedent that protects API specs - so this should really not be the case.
Our [API](<a href="https://www.modio.se/pages/api-doc.html" rel="nofollow">https://www.modio.se/pages/api-doc.html</a>) documentation is public, but that makes for little value, as identification is made using TLS certificates.<p>Yes, the API is public, but you need a Cert bound to your user data to get anything from it.