When you write an API with public endpoints, you most likely want other developers to use your API. One must-have requirement is a good documentation that allows others to discover, understand, and use your API. There are plenty of tools that help you to generate documentation out of code or even host it for you, but here are the key points that you should think about, before you start writing your documentation.

Here are a few key points, that are best practice. Our own documentation might not be perfect, but the notes in this blog post capture what we are striving for.

Structure for your Audiences

Keep in mind, that the readers of your documents might be different from you. They might

• be product managers who ask “can I do X with this API”?
• be CTOs who compare different available APIs.
• be developers, looking into how to integrate the API.
• be developers who want to debug an issue they have when calling your API.

The content, but also the structure of your documentation should invite all those audience groups. CTOs and product managers are interested in a high level overview, while the developer who will integrate your API into another system might want to read from A to Z to get a complete picture. The developer who needs to debug an issue might directly jump into one specific endpoint of your API.Ideally you will have a structure that follows:

1. Introduction
 - What value does this API generate / what is it's purpose.
 - Link to Tutorials
 - Version notes, links to migration guides and newer doc versions
2. General information
 - Domain specific context
 - Authentication
 - Pagination & limits
 - Rate throttling
 - General format constraints
 - Custom HTTP headers
x. Group of API endpoints
 x.y Endpoint y
     - what does it do? (plain English)
     - input parameters / formats
     - output / return codes inclusive example of _happy case_
     - possible errors (refer to general information when applicable)
     - example
 x.y+1 Endpoint y+1...
x+1. ...

Make use of hypertext by linking between API endpoints, whenever applicable. If your API is part of a product, link from the documentation to the product pages and vice versa. Ideally you link between endpoints or to the general information, whenever advisable. When you reach fame and your API is discussed on StackOverflow, you also want to have permalinks to every single headline and subheading. This way people can easily refer to any piece of information. When you put all your documentation onto a single page, readers can use their browser’s in-page search to quickly navigate.

If you look for inspiration look at the Stripe API documentation.

Design Choices

Use an easy to read, high-contrast design with a large font. Use boxes in a different color to emphasise on important details. Source code examples and written text should be easily distinguishable from another. Do not over-design and keep it simple, such that readers can copy sections and examples with ease (line numbers in a 5 line code snipped are useless and will be annoying, when pasted into an editor).

A great template, that we also use at Aquaplot is Slate. It implements a design similar to the Stripe API and makes it easy to write documentations that look good.

Satellite Documents

A complete documentation might still be intimidating for newcomers. If you have an SDK, put a Tutorial section into the readme or wiki of that SDK’s repository and link heavily between your API documentation and the tutorials. If you support only a single SDK or you provide only examples in one coding language, you can also include the tutorial into your API documentation. No matter where you put the tutorial - make the complete sources available for download so your users can directly jump into trying out our API.

Customized Examples & Client Technologies

If you have certain placeholders in your code examples, such as curl https://api.acme.com/foo?key=YOUR_SECRET_KEY, you can help readers by programmatically change that placeholder with the API key of the currently logged in user. If you do so, replace the placeholder on the client side. Then you can continue to serve the documentation as static HTML and you can benefit from caches.

In case you want to provide many example snippets in different languages, ask experts on these technologies to check whether you accidentally made some severe mistake.

Writing Style

Well, that really depends on you and the way your product should be presented. But personally I enjoy reading IETF documents (RFCs). The precise but brief nature is hard to achieve. Browse through a few of them before starting to write, eg. RFC7230.

No matter which style you write in, you must get feedback from people, who were never involved with the API, but are in at least on of your four audience groups. Only by doing so you will be sure that readers will be able to pick up the general concepts of your API.

Versioning

You do want to version your API documentation for the same reason you want to put versions on your API. Endpoints will change, become deprecated, or will be split up into several API calls. Put the API version your documentation addresses at a place that is always visible (if you have a sticky header, put it there). The default version of your documentation should be the latest stable version of your API endpoint. Put big deprecation notes on all API doc versions and refer to migration guides (like Google Adwords API does).

Conclusion

This note gave you a brief overview, what key points you should consider, before or while writing an API documentation. Do not be afraid to improve existing documentations. They are living documents, like your API source code.

Good examples for API documentations are: - Context.io - Stripe API - Travis CI API - Parse