Why isn't your API specification public?
1–10 of 30 posts
Re: Why isn't your API specification public?
#2A 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.
Re: Why isn't your API specification public?
#3Not a single mention of the human element, which I will theorize is the main reason.
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?
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.
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 feel 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.
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.
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.
Re: Why isn't your API specification public?
#4Not a single mention of the human element, which I will theorize is the main reason. 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? Most developers I know love getting something to work. They love the feeling of having mastered something to the point that…
Hi, the author here. I think its a good point you make. However, I believe being based on JSON or YAML, many of the specification formats provide at least some degree of readability. Also, one idea of them is to provide the basis for creating consistent, human-targeted documentations (see the right side of http://editor.swagger.io/). One might say these documentations are not good enough, but that would be a discussion about the quality of the tooling, rather than an argument against formal specifications per se.
Re: Why isn't your API specification public?
#5I'm wondering if there's actually a widespread demand/need for public API specs.
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).
What (potential) use case am I missing?
Re: Why isn't your API specification public?
#6Not a single mention of the human element, which I will theorize is the main reason. 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? Most developers I know love getting something to work. They love the feeling of having mastered something to the point that…
I agree with the argument: developers like reading web pages that describe how to use API, covering rationale of API design, gotchas, code samples.
However, what if the specs were able to capture what is in such human-readable pages (for example https://docs.cloudant.com/)? What if API spec could be automatically derived out of HTML pages? Embed some metadata in HTML page and then we have both cake (human-readable) and eat it (machine-readable)?
Re: Why isn't your API specification public?
#7I'm wondering if there's actually a widespread demand/need for public API specs. 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). What (po…
What do you think about automatic generation of client-code in various languages?
With regards to the bugs, were they a result of the implementation and the specification getting out of sync? Would automatic means for creating / maintaining specs be able to help here?
Re: Why isn't your API specification public?
#8Our [API](https://www.modio.se/pages/api-doc.html) documentation is public, but that makes for little value, as identification is made using TLS certificates.
Yes, the API is public, but you need a Cert bound to your user data to get anything from it.
Re: Why isn't your API specification public?
#9I'm wondering if there's actually a widespread demand/need for public API specs. 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). What (po…
As an API provider, would indexing and discovery of your APIs be of value to you?
As a developer with discovery may enable synthesis and composition of APIs.
Sites like ProgrammableWeb (http://www.programmableweb.com) and API Harmony (http://apiharmony-open.mybluemix.net) would do better if they could understand what changed and what is available.
I lead the API Harmony team at IBM Research and this information would be extremely valuable.
Re: Why isn't your API specification public?
#10Our [API]( https://www.modio.se/pages/api-doc.html ) documentation is public, but that makes for little value, as identification is made using TLS certificates. Yes, the API is public, but you need a Cert bound to your user data to get anything from it.
Spidler, what you show is nice, to the point documentation for human consumption. The API specification mentioned is related to things like OpenAPI Specification (http://swagger.io/specification/) or RAML (http://raml.org) which are used to model APIs in a machine readable way and then lend to automating things like documentation, SDKs or mock test servers.
This is an orthogonal issue to whether or not the API itself is publicly accessible.