4 ms·
Ask HN: Why is there no standard for (RESTful) API documentation?
I just had to read through incomprehensible API docs. It's painful. Why isn't there a standard for API docs, just like there is a standard for language-specific library docs (e.g. rubydoc)?
- cotsog 13y agoAlso check http://apiary.io http://apiary.io.
- veesahni 13y agoThere isn't a standard for RESTful APIs, which makes it hard to provide concrete standard for RESTful API docs.
- dragonwriter 13y agoThere'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 13y ago(Disclaimer: I work for Mashape). There are tools/services that help address this like Mashape, IO Docs, Swagger, etc.