25 ms·

Not a single mention of the human element, which I will theorize is the main reason. Psychologically, looking at a formal specification is pretty intimidating.

Not 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.

ewittern 11y ago
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/ 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.
aslom 11y ago
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/ 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)?
- frio 11y ago
  That sounds very much like [API Blueprints](https://apiblueprint.org/ https://apiblueprint.org/), which [Apiary](https://apiary.io/ https://apiary.io/) back. I tried to get the organisation I work for to standardise on them (being able to run tests from a versioned API specification seemed like a fantastic way to hit two birds with one stone), but sadly, couldn't convince enough people.
  - ewittern 11y ago
    What were the reasons people brought up against doing this?
    - frio 11y ago
      Mostly inertia. We're a large-ish company; I work in a remote office away from the majority of dev, and technical direction needs marketing. We ended up using Swagger, which doesn't solve as many of our problems (having documentation generated from code isn't as robust from a testing POV, particularly when your RESTful API is versioned), but my "perfect" is the enemy of the company's "good" :).
  - seanp2k2 11y ago
    It also sounds like Swagger + OpenAPIs: https://openapis.org https://openapis.org
- bbrennan 11y ago
  I actually have two related projects here: Scrape HTML to swagger: https://github.com/bobby-brennan/scrape-to-swagger https://github.com/bobby-brennan/scrape-to-swagger Swagger to HTML docs: https://github.com/lucybot/lucy-console https://github.com/lucybot/lucy-console We also have a commercial version of the latter which you can see at any-api.com
  - ewittern 11y ago
    Cool projects, thanks for pointing them out! So, the scrape-html-to Swagger one would basically allow you to keep Swagger up to date as you change the human-readable API documentation? In that case, someone still has to make sure the API documentation is in sync with the source code, right?
bbrennan 11y ago
I don't think anyone is arguing that machine readable specs should take the place of human readable documentation. Specs are helpful for testing, integrations, and generating HTML docs. I agree the API provider's primary concern should be Developer Experience, and understand why creating a spec often takes a back seat. But I suspect that soon it will be seen as critical for any production grade API to have a machine readable spec. I view specs as analogous to unit tests - it doesn't get you closer to a deliverable product, but it makes the development lifecycle much less painful.
catnaroek 11y ago
The IETF's RFCs are hardly ever "formal". At best they have a formal grammar, but never a formal semantics. And I disagree that formal specifications are intimidating. A formal specification is just code, so if you have trouble understanding something, you can enlist the computer's help. On the other hand, if an informal specification isn't clear to you, you are more or less screwed.

ewittern 11y ago

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/ 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.

aslom 11y ago

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/ 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)?

frio 11y ago
That sounds very much like [API Blueprints](https://apiblueprint.org/ https://apiblueprint.org/), which [Apiary](https://apiary.io/ https://apiary.io/) back. I tried to get the organisation I work for to standardise on them (being able to run tests from a versioned API specification seemed like a fantastic way to hit two birds with one stone), but sadly, couldn't convince enough people.
- ewittern 11y ago
  What were the reasons people brought up against doing this?
  - frio 11y ago
    Mostly inertia. We're a large-ish company; I work in a remote office away from the majority of dev, and technical direction needs marketing. We ended up using Swagger, which doesn't solve as many of our problems (having documentation generated from code isn't as robust from a testing POV, particularly when your RESTful API is versioned), but my "perfect" is the enemy of the company's "good" :).
- seanp2k2 11y ago
  It also sounds like Swagger + OpenAPIs: https://openapis.org https://openapis.org
bbrennan 11y ago
I actually have two related projects here: Scrape HTML to swagger: https://github.com/bobby-brennan/scrape-to-swagger https://github.com/bobby-brennan/scrape-to-swagger Swagger to HTML docs: https://github.com/lucybot/lucy-console https://github.com/lucybot/lucy-console We also have a commercial version of the latter which you can see at any-api.com
- ewittern 11y ago
  Cool projects, thanks for pointing them out! So, the scrape-html-to Swagger one would basically allow you to keep Swagger up to date as you change the human-readable API documentation? In that case, someone still has to make sure the API documentation is in sync with the source code, right?

bbrennan 11y ago

I don't think anyone is arguing that machine readable specs should take the place of human readable documentation. Specs are helpful for testing, integrations, and generating HTML docs. I agree the API provider's primary concern should be Developer Experience, and understand why creating a spec often takes a back seat. But I suspect that soon it will be seen as critical for any production grade API to have a machine readable spec. I view specs as analogous to unit tests - it doesn't get you closer to a deliverable product, but it makes the development lifecycle much less painful.

catnaroek 11y ago

The IETF's RFCs are hardly ever "formal". At best they have a formal grammar, but never a formal semantics. And I disagree that formal specifications are intimidating. A formal specification is just code, so if you have trouble understanding something, you can enlist the computer's help. On the other hand, if an informal specification isn't clear to you, you are more or less screwed.