Have you ever bought a piece of furniture and realized that no instructions would have been better than the ones you got? (I’m looking at you IKEA and your three-drawer chest.)
For customers, poor documentation is frustrating and can leave a bad impression. Since these customers will be less likely to keep the item or purchase from the company again, poor documentation not only affects the user experience — it also affects the company’s bottom line.
This is true for furniture companies, food blogs, and API providers. API providers, or companies that build, expose, and often monetize application programming interfaces (APIs), need to provide API documentation that’s clear, specific, and up-to-date. Otherwise, it won’t matter if they have the greatest API — no one will use it if they don’t know how to.
As APIs become more prevalent in the digital economy, it’s likely that you will either consume or develop APIs — or both. For that reason, it’s important to understand how to not only write but read API documentation. Let’s start by defining what API documentation is.
What is API Documentation?
API documentation is essentially an instruction manual that explains how to use an API and its services. This manual might contain tutorials, code examples, screenshots, and anything else that helps users better understand how to work with the API.
You can also think of documentation as an agreement between two parties. It outlines how the second party and its software will respond when the first party sends a certain type of request.
These types of requests — known as API calls — are described in the documentation so developers know what they can ask the API to do and how.
Good API documentation describes its endpoints, explains why you’d use them, and offers very specific examples of how you’d use them — all in a way that’s accessible to both beginners and more advanced users. Bad API documentation is overly technical and text-based, and therefore not accessible to all users.
Below we’ll walk through how to write good API documentation in seven steps.
How to Write API Documentation
Understand the API’s users.
Map out the user journey.
Start with the fundamentals.
Add code examples.
List your status codes and error messages.
Write and design for humans.
Keep your documentation up-to-date.
1. Understand the API's users.
As with any content strategy plan or UI design process, the first step of writing API documentation is understanding the target audience. That will require understanding the types of users you’re targeting, what value the content provides them, and how they actually use the content.
With API documentation, there are two main groups of users to keep in mind when writing. There’s the users who will be using and interacting with the API and therefore looking for tutorials and code examples. This group will primarily be made up of developers. Then there’s the users who will be evaluating the API and its pricing, rate limits, and security to see how it aligns with their business needs and goals. This group will primarily be made up of CTOs and product managers as well as some developers.
You’ll have to write with both these personas in mind to ensure the documentation provides a good experience for every reader.
2. Map out the user journey.
Like any other product, APIs must provide content for every stage of the buyer’s journey. That means documentation should explain what the API can do (or what problems it can solve), the variety of functions and endpoints it offers, and how it’s different from competitors.
Some basic questions that API documentation should answer are:
Why this API?
How do I get access to the different tools and endpoints?
What should I do after getting access?
How do I use [this specific feature]?
3. Start with the fundamentals.
Every API is unique. There’s an API for embedding Instagram photos on an ecommerce app. There’s an API for providing access to thousands of hotels on a travel blog. There’s even an API for integrating a Yoda translator on a website. But there are fundamentals that every API documentation should cover. Let’s take a look at a few below.
Since authentication is essential for keeping an API’s data safe for developers and users alike, an API will usually have multiple authentication schemes. API documentation must explain each of its authentication methods so users can access and start consuming the API. The YouTube Data API, for example, supports two types of authorization credentials. Its documentation explains how to use OAuth 2.0 and how to get an API key so users can opt for the method they’re more comfortable with.
It’s essential that API consumers are informed about changes to the APIs they use. It can help ensure they properly maintain their applications and fully leverage the potential of the API platform. Twitter’s API documentation has a changelog, where it documents all changes made to The Twitter Developer Platform, including new functionality and products.
API documentation has two main goals: to make it as easy as possible for developers to start using the API and to make them quickly understand the API’s full potentialI. A great way to accomplish both these goals is to provide code examples for each API endpoint. That way, developers can understand the most critical functions of an endpoint and start with some code that they can then tweak to meet their exact specifications.
Here’s an example from HubSpot’s API documentation. The code example shows how you can use the CRM API endpoint to filter contacts by a specific property value.
API documentation should clearly outline the status codes and error messages that users can expect when making an API call. Ideally, every response will be paired with a brief description so users can understand when they made a successful API call and when they didn’t, and be able to resolve any errors they encounter themselves. Often, this information is placed on its own page. Here’s an example from the documentation of the RESTful Amazon Drive API.
You want to write, structure, and design your API documentation in a way that’s easy for users to read and browse. That means presenting and organizing information according to the user’s context and their needs. A user’s context is everything related to where, when, why, and how the user will be seeking out and engaging with the content. Their needs include their goals, behaviors, and expectations as well.
The best API documentation is written both for beginners who are completely unfamiliar with the API and developers who are intimately familiar with the API. It avoids technical jargon when possible and provides additional context or internal links when not possible. It also offers informative sections like Getting Started as well as examples and tutorials, which novice users will need and more advanced users can skip over. Take a look at the Twilio doc below, which includes an internal link to a post on APIs as well as a section called “What’s a REST API, anyway?”
To ensure users can pick and choose the content they need, navigation is essential when designing API documentation. Best practices include having a sticky header and sidebar so users don’t have to scroll up and down the page to navigate to another part of the documentation and offering search functionality. Other design considerations include typography, color schemes, and layouts. The three-column layout of the Twilio doc above is considered ideal for documentation with lots of code examples. The sans serif font and contrasting colored links are also excellent design choices.
To ensure the best experience for API consumers and attract new users, it’s essential that API documentation is maintained. In the past, API documentation existed as PDFs or static web pages that were difficult and time-consuming to update. Now, there are tools to help you create dynamic and interactive docs that can be auto-updated. Redocly and SwaggerUI are just two examples.
If you’re consuming an API instead of providing one, then you’ll need to understand how to read it. While the approaches to writing and reading it are similar — look for the fundamentals, try the code examples, and so on — they are not identical. Let’s take a closer look at how you can read API documentation to understand what’s possible with a particular API.
Start with the overview.
Most API documentation will begin with an overview of what the API does, how to connect to it, and how to use it properly. You don’t need to understand every part of the overview, but you should read through it thoroughly.
HubSpot’s API documentation begins by explaining the purpose of HubSpot’s APIs, what protocols and languages it uses, and what its authentication schemes are. In the left sidebar and the Quick Links section at the bottom, you’ll find important links to its usage guidelines and rate limits, testing accounts, changelog, and everything else you need to get started using the APIs.
After getting an overview of the API, skim the reference doc that lists out all the API’s functions (also known as methods). At this point, there’s no point in reading them thoroughly or memorizing them all. Instead, take a closer look at a method you’re particularly interested in. By looking through its parameters and examples, you can get an idea of whether you could successfully use the API to perform the exact action you want to take.
For example, let’s say you’re interested in using Mailchimp’s API to create an automated email workflow so that they’re sent to subscribers when triggered by a specific date. In that case, you’d navigate to the API Reference and click Automations. Then click the method you’re interested in — POST / automations, in this case — and look at its parameters, responses, and error messages.
Now that you have an idea of whether you can use the API to perform a desired function, check out a tutorial. Since the best API documentation should enable you to get started quickly, most will include detailed tutorials for completing tasks. You should read through at least one tutorial to see if you like the tone, level of detail, and examples, and are able to follow along. You can even try to complete the tutorial.
Stripe’s API documentation is well-known for its in-depth tutorials. In addition to text-based tutorials, it’s also testing a new interactive format. This format breaks down a function — like embedding a custom Stripe payment form in a website or application — step-by-step and provides the relevant code for each step, which users can copy in one click. The text is placed side-by-side with the code module.
As more companies consume and provide APIs to deliver seamlessly integrated user experiences, knowing how to write and read API documentation is becoming an increasingly valuable skill. When creating or evaluating API documentation, make sure it’s easy to read and navigate and clearly communicates the value of the API to developers and non-developers. This will ensure users can get started working with your APIs, or you can do so with someone else’s.
Originally published Jan 8, 2021 7:00:00 AM, updated January 08 2021