Best Practices API Documentation

Best practices for API documentation

This is a list of best-practice recommendations for creating API documentation, from a variety of sources. The list is numbered to facilitate referencing, not to indicate importance.

1. A good structure for developer documentation:
   • Overview
   • Quick start, including installation
   • Tutorials / sample code
   • Drill down to reference guides (“And it must look cool.” Sarah Maddox, slides 10, 25, 26) (Peter Gruenbaum)
2. Tools like Swagger, Apiary, and Iodocs are helpful, but are not great at being the sole documentation for a REST API. Goals of good API documentation:
   • Provide a high-level introduction. "This is what the API is, what you can do with it, how our URLs/responses are designed."
   • Include a quick-start or "hello world" tutorial.
   • Provide real, syntax-highlighted example responses, next to the URLs that generated them.
   • Can be improved by users (for example, is versioned in GitHub).
   • Provide explanations of each field, and what promises that field is making (for example, possible enumerated values, whether it can be null, what type of data, an example value).
   • Is clearly written, in professional language; no typos or grammatical errors. (Standards for API Documentation)
3. Examples in API docs:
   • Good documentation includes examples, but good examples are not common enough.
   • Good documentation does not rely on examples.
   • An example can provide a base to start from, a beginning point for further hacking.
   • However, an example, like a picture, can't say "ain't": Examples can only show you what you can do, never what you cannot do, or what you should not do.
   • Further, examples are inductive, and it takes a massive amount of induction to get all of the rules of a system. However, once someone's done something, they've internalized it a lot better than if they've only read about it.
   • Examples should, therefore, allow people to see the intended use of an API. How do the developers want people to use their API to solve problems?
   • Documentation is permissive: "You can use this tool to do this."
   • Examples are normative: "You should use this tool this way."
   • Both are needed. (An API is only as good as its documentation, the top comment)
4. Guidelines for good sample code:
   • Relevant information should be grouped together.
   • Clarity is more important than efficiency or robustness.
   • Simplicity is more important than a good-looking UI. (Peter Gruenbaum one and two)
5. REST API best practices, overall structure:
   • Overview
   • Why use this API
   • Getting started help
   • Base URL
   • Getting an API key
   • Authentication
   • Error handling
   • HTTP status codes (Marta Rauch, slide 9)
6. REST API best practices, reference section structure:
   • Name
   • Overview
   • URL structure
   • Methods - GET, PUT, POST, DELETE…
   • Parameters
   • Descriptions
   • Remarks
   • Examples
   • REST endpoints (Marta Rauch, slide 10)
7. Two classes of API users:
   • The smaller class is folks who read every function completely, like mission-critical clients or code reviewers. Each function must be perfectly specified; nothing can be left to guesswork.
   • The larger class is folks who just want to get things done; they only skim docs. To help them, assume that most users will not actually read the documentation, and:
     • design the API to avoid "surprises" in otherwise-straightforward functions
     • explicitly highlight the non-trivial bits in the docs
     • provide recipes for common operations
     • include placeholders for methods not in the API but nonetheless desired. For example, to do Z, use function X and then Y. (Creating Great API Documentation, first answer, by Uri)
8. Developers like customized API explorers for REST APIs. But, we are not a web service, so we can just recommend tools like Advanced REST Client/Chrome or RESTClient/FireFox. (My conclusion after reading Sarah Maddox)
9. This article is written by Jacob Kaplan-Moss, a core contributor to Django, and I like it. He disdains generated reference materials, but I’m not sure we’ll have resources to do otherwise, initially.
10. Example JavaScript API: Google Maps
    • Getting started
    • How-to guides for common use cases
    • Reference
11. Example REST API: Twitter
    • Overview and getting started
    • How-to guides for common use cases
    • Reference
12. Example Java-based API: Google Maps for Android
    • Overview
    • Getting started
    • How-to guides for common use cases
    • Reference
13. Create automated tests for code samples. (Sarah Maddox)
14. Perform collaborative (in-person) documentation plus sample code reviews. (Sarah Maddox)