

Ask HN: Why is there no standard for (RESTful) API documentation? - dennybritz

I just had to read through incomprehensible API docs. It&#x27;s painful. Why isn&#x27;t there a standard for API docs, just like there is a standard for language-specific library docs (e.g. rubydoc)?
======
dragonwriter
There's no standard for RESTful API docs because a RESTful API, per se,
doesn't need docs. If an API is really RESTful, the content types used in it
need documentation which describes both the content structure and the
meaningful operations against it, and with those the API is self-describing.

Of course, most "RESTful" APIs are variations on RPC over HTTP, not actually
RESTful.

------
ismaelc
(Disclaimer: I work for Mashape). There are tools/services that help address
this like Mashape, IO Docs, Swagger, etc.

------
veesahni
There isn't a standard for RESTful APIs, which makes it hard to provide
concrete standard for RESTful API docs.

------
cotsog
Also check [http://apiary.io](http://apiary.io).

