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.