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

Like others, I use the Apiary's Markdown format, using aglio to generate a HTML page from it. I also use Protagonist to convert the documentation to a JSON object that Python code can consume and verify that there's a 1:1 relationship between documented and implement API endpoints, as well as as arguments passed. There's room for further validation as my API endpoints have type checking and permissions declaratively configured (via Python decorators).

I tried RAML -- it makes sense for quick prototyping of your resources and methods, but I oculdn't see myself writing too much documentation as a giant nested YAML document.

I also tried apidoc which might make sense of you have internal documentation you wan to quickly expose. However my docs are longer than the code implementing them, so I don't like mixing them in as e.g. apidoc would require. I'd prefer lots of English in my documentation and it seems odd to conflate hints on how to use an API call as an external user with the implementation of it. Compare Sphinx-generated Python docs with some auto-generated python library documentation.

The apidoc versioning system is pretty cool, though if you are making a public REST API backwards-incompatible version changes should be avoided.

Isn't this why enterprises favoured things like SOAP web services with XSDs and WSDLs? The verbosity acts as human and machine-readable documentation, and the files can be used to generate client code.

Ignoring the benefits of using HTTP as the request transport mechanism, this seems like another cycle of people coming up with a comprehensive but complex solution, other people getting frustrated with the complexity and developing a simpler solution, then filling in the gaps (such as documentation) until the solution is a complex patchwork of competing libraries, none clearly better than the others, leading to fragmenting of mindshare and expertise...

At least the last time I looked at Swagger, it was very much URL/endpoint-focused. Hyperlinks, while documentable, are not first-class citizens. In a real hypermedia-driven API, you want to document the links, not the URLs, as the API users will be using these named links, and not constructing URLs, to access functionality.

Hi, I'm Dredd developer and here are my comments on Dredd - API Blueprint testing tool:

- 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

This I can't confirm, presence of object keys is validated on any level.

- 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

This is true, but it’s by design. In Dredd URI parameters are inherited from resource to action, but there is no way how to filter out unwanted parameters from resource under action section.

In this case I assume that `skip` and `take` parameters belong only to GET action (retrieving collection), so its imho a non-sense to discuss them on the resource level because they will be propagated to any action under that resource.

Thank you for very interesting feedback!