Best Practices For APIs: Planning (3)
Provide Documentation
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.
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 (e.g. 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' 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.
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.
Error Handling
Providing good error handling is essential if you want to give the developers using your API an opportunity to correct their mistake. Error messages should be clear and concise and pitched at the appropriate. Messages such as "Input has failed" are highly unhelpful and unfortunately fairly common. Avoid:
- Inconsistency (e.g. different variable order in similar methods).
- Over-general error reporting (a single exception object covering a number of very different possible errors).
- Over-complicated request payload - having to send a complex session object as part of each Web service call.
Log API traffic with as much context as possible to deal with resolution of errors. Provide permanently addressable status and changelog pages for your API; if the service or API goes down for any reason, these two pages must still be visible, preferably with why things are down.
Provide APIs In Different Languages
A simple Web API is usually REST/HTTP based, with XML delivery of a simple schema e.g. RSS. You may want to offer toolkits for different languages and support a variety of formats (e.g. SOAP, REST, JSON etc.).
Try to provide APIs in XML format then it can also be read by other devices such as kiosks and LED displays. Making returned data available in a number of format (e.g. XML, JSON, PHP encoded array) it saves developers a lot of wasted time parsing XML to make an array.
Provide sample code that uses API in different languages. Try to be general where possible so that one client could be written against multiple systems (even if full functionality is not available without specialization).
For database APIs, provide a variety of output options - different metadata formats and/or levels of detail.
Acknowledgments
This document is based on advice provided by UKOLN's Good APIs project. Further information is available at <http://blogs.ukoln.ac.uk/good-apis-jisc/>.
