From the Department of Bad Ways to Document APIs, referring to no service in particular:
- Don’t refrain from changing and updating the specification after release. Consumers of your service will value API tweaks and improvements over stability.
- Don't provide a changelog for the specification. Nobody reads them anyway, and they're such a hassle to maintain.
- Similarly, don't notify consumers of changes to the specification by RSS or Atom, since nobody uses them anymore. They're all such avid fans of your service that they'll take the time to re-read the API specification every few weeks anyway.
- Move the documentation around every few months and re-brand it. Shiny logos are cool, and maintaining redirects from old documentation locations is too hard.
- Also don’t worry about moving your issue tracker around every few months, or closing all the old bugs every time. If nobody's touched a bug in months, it's probably been fixed, right?
- Annotated API call examples are worth 1000 times more than boring, verbose, precise descriptions of constraints, error behaviour and motivations for the API design.
- Version numbering is hard to get right, and consumers always use the highest-numbered version, so there's no need to annotate APIs with the version or date they were last changed or introduced.
On the other hand, some good ways to document APIs:
- Allow anchor linking to documentation subsections.
- Clearly mark deprecations and provide a deprecation schedule.
- Provide a sandboxed API playground for testing API calls.
- Provide worked client examples in multiple programming languages.
Turns out, documenting a large API which is expected to be consumed by thousands of people requires a lot of careful work.
"Annotated API call examples are worth 1000 times more than boring, verbose, precise descriptions of constraints, error behaviour and motivations for the API design."
This doesn't sound right to me.
You need to make sure the examples: a) don't parse/compile, b) use outdated API that no longer works, c) has logical flows, d) show contrived use cases (e.g. don't handle obvious error cases). Otherwise they're far too useful. All of these are common in my experience.
I couldn’t possibly be so cynical.
To be fair, the API specification I had in mind doesn’t make any of these mistakes; but it’s good to note them anyway, in the hope that it helps others in future.
At SaasDoc, we're trying to make Api Documentation simple and more useful. You have many good points and we agree that too many docs contain useless materials. All that noise just gets between api consumers and the api itself.
We're getting set to beta test our app in the coming weeks. Please let us know if you're interested. We'd love to hear your feedback!