Why isn't your API specification public? • Hacker News Board

Re: Why isn't your API specification public?

#11

Post by 7373737373 » Wed, Apr 27, 2016, 8:43 PM UTC

ewittern wrote: post #7

realityking wrote: post #5

I'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?

I spend the last few weeks trying to find an appropriate SDL for my project but have otherwise no experience in creating APIs.

In my opinion, API specs should probably be generated from code and its documentation, and not the reverse. This is because it is the code and not the spec which is subject to most change and only the endpoint interfaces/signatures can be generated. API specifications could also be more easily transformed by middleware (e.g. when renaming endpoints, combining APIs) if they were machine generated.

As was described above, only few people are acquainted with service description languages, and deeper changes in their semantics over time or the choice of an alternative would require a manual rewrite. Also, some SDLs seem to impose their own higher level ontologies and name spaces, which is another major obstacle to usage for simple systems.

Re: Why isn't your API specification public?

#12

Post by frio » Wed, Apr 27, 2016, 8:52 PM UTC

aslom wrote: post #6

andrewstuart2 wrote: post #3

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…

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)…

That sounds very much like [API Blueprints](https://apiblueprint.org/), which [Apiary](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.

Re: Why isn't your API specification public?

#13

Post by krsyoung » Wed, Apr 27, 2016, 8:56 PM UTC

7373737373 wrote: post #11

ewittern wrote: post #7

Earlier quoted context omitted.

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?

I spend the last few weeks trying to find an appropriate SDL for my project but have otherwise no experience in creating APIs. In my opinion, API specs should probably be generated from code and its documentation, and not the reverse. This is because it is the code and not the spec which is subject to most change and only the endpoint interfaces/signatures can be generated. API specifications could also be more easil…

First, it is too bad that you spent weeks and probably didn't find the "right" solution (because it doesn't seem to exist).

Second, I like your enthusiasm for specs from code ... the problem (opportunity?) today is that the specifications intertwine human readable descriptions / summaries with the actual endpoint / payload information.

I would hate for my devops pipeline to kick-off because somebody fixed a typo in some human focused in-line documentation. I personally don't think it belongs in the code but absolutely agree with the spirit of your comment (if you keep them separate it is more work and they will get out of sync!).

The best luck I have is working within the specification (i.e. Swagger) and avoiding doing things that don't model well. This seems backwards, but for most of the development I've been involved with to date it has served the projects well.

Interested if others have had luck embedding API specs into code.

Re: Why isn't your API specification public?

#14

Post by bbrennan » Wed, Apr 27, 2016, 9:04 PM UTC

aslom wrote: post #6

andrewstuart2 wrote: post #3

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…

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)…

I actually have two related projects here:

Scrape HTML to swagger: https://github.com/bobby-brennan/scrape-to-swagger

Swagger to HTML docs: https://github.com/lucybot/lucy-console

We also have a commercial version of the latter which you can see at any-api.com

Re: Why isn't your API specification public?

#15

Post by bbrennan » Wed, Apr 27, 2016, 9:13 PM UTC

andrewstuart2 wrote: post #3

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…

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.

Re: Why isn't your API specification public?

#16

Post by ewittern » Wed, Apr 27, 2016, 9:30 PM UTC

bbrennan wrote: post #14

aslom wrote: post #6

Earlier quoted context omitted.

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)…

I actually have two related projects here: Scrape HTML to swagger: https://github.com/bobby-brennan/scrape-to-swagger Swagger to HTML docs: https://github.com/lucybot/lucy-console We also have a commercial version of the latter which you can see at any-api.com

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?

Re: Why isn't your API specification public?

#17

Post by ewittern » Wed, Apr 27, 2016, 9:31 PM UTC

frio wrote: post #12

aslom wrote: post #6

Earlier quoted context omitted.

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)…

That sounds very much like [API Blueprints]( https://apiblueprint.org/ ), which [Apiary]( 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.

What were the reasons people brought up against doing this?

Re: Why isn't your API specification public?

#18

Post by ewittern » Wed, Apr 27, 2016, 9:33 PM UTC

krsyoung wrote: post #13

7373737373 wrote: post #11

Earlier quoted context omitted.

I spend the last few weeks trying to find an appropriate SDL for my project but have otherwise no experience in creating APIs. In my opinion, API specs should probably be generated from code and its documentation, and not the reverse. This is because it is the code and not the spec which is subject to most change and only the endpoint interfaces/signatures can be generated. API specifications could also be more easil…

First, it is too bad that you spent weeks and probably didn't find the "right" solution (because it doesn't seem to exist). Second, I like your enthusiasm for specs from code ... the problem (opportunity?) today is that the specifications intertwine human readable descriptions / summaries with the actual endpoint / payload information. I would hate for my devops pipeline to kick-off because somebody fixed a typo in s…

Mixing code with documentation is one concern. Another issue is that extracting the information needed to create a Swagger from source code is hard, especially when using dynamic languages (JavaScript, Python). One approach is to use dedicated annotators to relate code with parts of an API spec - but then you have the first problem again...

Re: Why isn't your API specification public?

#19

Post by IvanGoncharov » Wed, Apr 27, 2016, 9:59 PM UTC

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.

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.

I currently work on catalog which does exactly this, and you can see list of integrations here: https://github.com/APIs-guru/api-models#existing-integration...

Re: Why isn't your API specification public?

#20

Post by 7373737373 » Wed, Apr 27, 2016, 11:16 PM UTC

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.

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:

http://i.imgur.com/4mmckZ9.png https://gist.github.com/void4/523f23b50e1572e8ef60

I wonder what comes after that. Most probably different transports and patterns of interactions. http://iris.karalabe.com/ might show how it will look like.