Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: What's the best way to write an API spec?

news.ycombinator.com

Post reply on HN
Print view View original

21–30 of 58 posts

Re: Ask HN: What's the best way to write an API spec?

#21

Post by gdillon »

smt88 wrote: post #3

Have a look at http://apiary.io and http://readme.io

Hey, thanks for the tip. ReadMe.io cofounder here, happy to answer any questions about my service or API specs in general.

ReadMe.io currently focuses more on the "front end" of the API. We can ingest in-line comments made with the apiDoc.js [1] standard, and then use that description to build an API explorer and reference docs automatically. We like apiDoc because of how concise the comments are, and because they are kept very close to the code (no extra files to maintain). It's not as common as some of the other standards mentioned here, but it's — by far — the fastest and most straightforward way to describe an API.

[1] http://apidocjs.com/

Edit: this is how it's implemented within ReadMe.io: http://readme-sync.readme.io/v1.0/docs

Re: Ask HN: What's the best way to write an API spec?

#22

Post by davnola »

Here's a summary of the discussion (RAML vs Swagger vs Apiary vs RSpec...) we had at Lonely Planet: https://lonelyplanet.atlassian.net/wiki/display/PUB/API+Spec...

5 months in, we're happy with API Blueprint. We used to use Dredd for API validation but ran into to some limitations:

- Dredd does not perform any validation against the siren response beyond the first key level. For example, it does not validate if the class-name is user-events, or usr-events

- Dredd does not make any difference between Action parameters and Resource parameters. Then, an action POST to create user-events will have undesired url parameters. E.G: POST /user-events?take=0&skip=2 (The apib blueprint specs allows to make this difference: https://github.com/apiaryio/api-blueprint/blob/master/exampl...)

So one of our devs created a Ruby validator, https://github.com/nogates/vigia. See http://engineering.lonelyplanet.com/2014/11/18/vigia-integra... if you're interested.

Re: Ask HN: What's the best way to write an API spec?

#24

Post by matt_kantor »

rodw wrote: post #5

I guess I'll take this opportunity to plug my own little tool for this. I use Swagger [1] and more specifically Swagger UI [2] to generate interactive web-based documentation like the sample at [3]. But rather than relying upon source code annotations to have swagger auto-generate the documentation, or hand-writing swagger's verbose JSON structure, I created a little DSL for it as demonstrated at [4] and available on…

BTW, Swagger-codegen has [support for writing specs in YAML][1] too, if that's your thing.

My team makes uses generated Swagger API docs (via the swagger-play2 plugin), but to be honest the tooling around it is pretty half-assed. Having a machine-readable spec is a game changer, though.

[1]: https://github.com/swagger-api/swagger-codegen/wiki/Creating...

Re: Ask HN: What's the best way to write an API spec?

#25

Post by smt88 »

gdillon wrote: post #21
smt88 wrote: post #3

Have a look at http://apiary.io and http://readme.io

Hey, thanks for the tip. ReadMe.io cofounder here, happy to answer any questions about my service or API specs in general. ReadMe.io currently focuses more on the "front end" of the API. We can ingest in-line comments made with the apiDoc.js [1] standard, and then use that description to build an API explorer and reference docs automatically. We like apiDoc because of how concise the comments are, and because they ar…

I like apiDoc, too, and I spent a few days adding those comments to my code.

However, it's been months now, and the GitHub Sync section still says "temporarily disabled".

Is this feature really done? When can I use it?

I'm a bootstrapper and understand testing features by pretending they exist, but it's been a pretty long time...

Re: Ask HN: What's the best way to write an API spec?

#26

Post by pksunkara »

Disclaimer: I work for Apiary.

API Blueprint [1] is an open source API description format which can be used to intuitively describe an API.

MSON [2] is a recent addition to the above format which makes it easy to describe all kinds of complex requests and responses in the spec.

You can email me at pavan [at] apiary [dot] io if you have any more questions.

[1]: http://apiblueprint.org

[2]: http://github.com/apiaryio/mson

Re: Ask HN: What's the best way to write an API spec?

#27

Post by deeviant »

There is no single secret to making good API specifications.

But here are few things I've learned:

* The more comprehensive the documentation gets, the the quicker it gets outdated, un-useful, or flat out pants-on-fire lying. Define what the thing does and what assumptions are made, save detail for "gotchas". Be concise.

* Start out on a white board, run through each function, what it should do, what it shouldn't. This really is a huge benefit of spec'ing out a api, just sitting there thinking about it, tons of stuff comes up and you come out with a better product in the end.

* If the format you came up with can't be put into something like a table or spreadsheet, you probably doing it wrong. Sure you can get some sort of framework that lets you create all sorts of UML and create class/function shells or what have you, but I have never found these to create value or clarity. If you are spending more than 20-30 minutes outlining even a complicated function, your probably wasting time. Use time saved to create a clear system-wide DFD.

* Don't go deep into implementation detail at this stage, but at least think about it. Some much time can be saved with a little forethought here.

Re: Ask HN: What's the best way to write an API spec?

#28

Post by marquis »

rodw wrote: post #5

I guess I'll take this opportunity to plug my own little tool for this. I use Swagger [1] and more specifically Swagger UI [2] to generate interactive web-based documentation like the sample at [3]. But rather than relying upon source code annotations to have swagger auto-generate the documentation, or hand-writing swagger's verbose JSON structure, I created a little DSL for it as demonstrated at [4] and available on…

We love Swagger. It allows us to have uniform documentation across all our APIs regardless of dev writing style. It's a simple plan we can all stick to. Plus it gives you real API access inside the docs themselves. We highly recommend it and may I use this opportunity to thank the developer!

Re: Ask HN: What's the best way to write an API spec?

#30

Post by sm_sohan »

May I say, look at SpyREST (SpyREST.com) if you consider developing the API first and then produce the documentation automatically simply by exercising the API? This is an open-source tool, feel free to take a look.

I'm developing SpyREST and will be happy to discuss if you want to learn more.

Post reply on HN