Good APIs Project

Although a good API should be, by its very nature, intuitive and theoretically not need documentation it is good practice to provide clear useful documentation and examples for prospective developers. This documentation should be well written, clear and full. Inaccurate, inappropriate or documentation of your API is the easiest way to lose users.

“A key to using APIs effectively is the understanding of the key concepts they are based around and the types of interaction they are designed to facilitate. API documentation should not forget this high-level conceptual view as part of the orientation.“

Developers should give consideration to including most, if not all, of the following:

• Information on and links to related functions
• Worked examples and suggestions for use. The examples should be easy to clone, from different programming languages.
• Case studies. Real world examples in real world languages: PHP Java Ruby, python etc.
• Demos – if you want to entice someone to use your API you need good examples that can be re-used quickly. Provide a ‘Getting started’ for guide.
• Tutorials and walkthroughs
• Documentation for less technical developers
• A trouble shooting guide
• A reference client/server system that people can code against for testing and possibly access to libraries and example code
• Opportunities for user feedback, on both the documentation and the API itself
• Migration tips
• A clear outline of the terms of service of the API. e.g. This is an experimental service, we may change or withdraw this at any time” or “We guarantee to keep this API running until at least January 2012”
• Any ground rules.
• An appendix with design decisions. Knowing why an API developed the way it did can often help a new developer understand the interface more rapidly.

Good documentation is effectively a roadmap of the API that helps to orientate a new developer quickly. It will allow others to pick up and run with your API. Providing it on release of your API will result in less time spent taking support calls.

“Human effort is generally more expensive than compute cycles. Beyond a certain point, spending development effort optimising your documentation will be cheaper for the community as a whole than optimising your system.“

Other suggestions include using a mechanism that allows automatic extraction of the comments, such as Javadoc and providing inline documentation that produces Intellisense-type context-sensitive help.

“If an API has changed but the documentation hasn’t been updated then you can easily waste any amount of time before you realise that the instructions you’re following don’t match up to the pieces you got, IKEA-style“