Ask HN: What's the best way to write an API spec? • Hacker News Board

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

#41

Post by blt » Mon, Jan 19, 2015, 9:55 PM UTC

dkarapetyan wrote: post #33

Write some client code for how you want to use the API and then elaborate those examples by making references to the spec. This might seem backwards to you but you'll discover all sorts of edge cases and awkwardness in the process that you wouldn't have discovered by just writing the spec. You don't need any special tools to do that although apiary comes to mind as something worthwhile.

+1 on starting with use cases. Write the client code you'd love to write, and then figure out what API will make it possible.

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

#42

Post by simi_ » Mon, Jan 19, 2015, 10:07 PM UTC

simi_ wrote: post #7

We tried a lot of options at Lavaboom (including apiary, readme.io, swagger, etc) and ended up using Slate: https://github.com/tripit/slate

We ended up with Slate because:

1. readme.io is just painful to use for larger documentations; very GUI-oriented 2. apiary is basically just annoying in every way (I really like the company so I tried 3 separate times to get myself to like their product) 3. I dismissed a couple of self-hosted options that use JS to render the information, since I find that idiotic

Slate struck a good balance between (1) syntax (2) ease of use and (3) good looks, although I wouldn't call it prefect in any of those departments.

Disclaimer: the end result looks surprisingly better than what you'd expect.

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

#43

Post by sv3nss0n » Mon, Jan 19, 2015, 10:09 PM UTC

mrkd wrote: post #19

It looks like there are some options out there for REST APIs. Does anyone know of any API specs written for websocket APIs? I am working on creating a websocket API and would like to at least look at a few other examples.

This is something I am looking for as well. In my case I'd like to integrate a REST API with a Push Notifications API in a unified API specification. Today I have resorted to using JSON schemas/hyperschemas with custom templating using the Heroku's prmd tool. Works ok but has the drawback that it relies on my custom made templates...

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

#44

Post by Fiahil » Mon, Jan 19, 2015, 10:16 PM UTC

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…

Great work! I really liked your layouts.

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

#45

Post by liamcode » Mon, Jan 19, 2015, 10:30 PM UTC

I use http://apidocjs.com/

You define the API in comments within your code. When you run apidoc it scans your code and generates pretty documentation.

I tried various other solutions before this such as apiary.io. Apidocjs is really easy to update as it is part of your code, which also means it goes into your version control!

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

#46

Post by muaddirac » Mon, Jan 19, 2015, 10:39 PM UTC

gamache wrote: post #8

There have been an explosion of API specification formats in the last few years. No clear winner has emerged. JSON Schema and JSON Hyperschema are JSON-based formats for describing JSON and REST (hypermedia-driven) APIs. The formats make decent sense and can be used to generate docs, validators, client libraries, UIs, and more. http://json-schema.org/ API Blueprint is another emerging format for API description. It's…

I would also point out that API Blueprint allows you to describe your API responses with json schema. They sit at different levels - blueprint for specifying urls resources are accessed with, and json schema for validating the payload.

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

#47

Post by Chris911 » Mon, Jan 19, 2015, 10:46 PM UTC

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 use Swagger at work. Thanks for this!

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

#48

Post by rodw » Mon, Jan 19, 2015, 11:14 PM UTC

matt_kantor wrote: post #24

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

Thanks Matt.

I looked at swagger-codegen before createing swagger-dsl, and frankly it is pretty nice, but with respect to authoring the underlying Swagger specification document, swagger-codegen is just a direct YAML translation of the original Swagger JSON format.

In other words, swagger-codegen's YAML support is just a YAML-to-JSON transformation. It has the same redundancies and structural issues as Swagger's JSON, just in a YAML syntax.

My objective with swagger-dsl was to create a more human-oriented (more readable, less verbose, less error prone, more DRY, etc.) format for authoring those JSON documents for Swagger. It's not just JSON-as-YAML, it's a more author-oriented (as opposed to parser-oriented) way to describe the API.

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

#49

Post by ioseph » Mon, Jan 19, 2015, 11:32 PM UTC

We've just started designing a new api and gone done the json-schema path which is particularly suitable since we're using json-rpc over websocket / http post.

Aside from that whatever tool you use, having markdown as the base source is really useful as you can then display it however you want while still quickly read it in a terminal.

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

#50

Post by kikibobo69 » Mon, Jan 19, 2015, 11:37 PM UTC

My former colleagues have been working on http://apidoc.me/ (https://github.com/gilt/apidoc). I really like this approach, which is basically:

1. specify the api in json 2. apidoc generates really nice api documentation 3. apidoc generates a single-file client for the service (currently ruby or scala) 4. apidoc generates a routes file for play2

It's scala-biased at the moment because that's their tech stack, but in practice an api-first approach seems to lead to higher quality APIs compared to just hacking something together and annotating it to extract docs. Also having a really nice client without a complicated compile-time dependency graph (on the JVM) feels like a sweet spot.