API documentation is one of the most important aspects of technology and software development. 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.)
Poor documentation frustrates customers and leaves a bad impression, impacting both user experience and the company's bottom line. API providers must provide clear and up-to-date documentation. Without it, even the greatest application programming interfaces (APIs) will go unused if users don't know how to use them.
- 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
- How to Read API Documentation
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.
Pro Tip: 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]?
Pro Tip: Mapping out the user journey can improve the delivery of the documentation and help with maintaining it over time.
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.
Pro Tip: The fundamentals may look a little different from project to project, so leave a little room for adaptation where needed.
Authentication
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.
Rate Limits
Like user authentication, rate limiting can help prevent an API from being accidentally or intentionally abused. An API rate limit is the number of times you can send a request to an API in a given period of time. These constraints need to be clearly stated in the API’s documentation so that users know how to properly use the API and what it’s capable of. This information is most often found in the Terms of Use.
Terms of Use
Terms of Use (or Service) is the legal agreement between a service provider and person who wants to use the service. The latter must agree to comply with those terms in order to use the service. In API documentation, the Terms of Use must clearly define how the API consumer should ideally use the API. This will help ensure that consumers are making the best use of the API platform. Take a look at the introduction of the Shopify API Terms of Use.
Changelog
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.
4. Add code examples.
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 potential. 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.
Pro Tip: Code examples help provide clear instructions; they can also allow a simplistic approach to plug-and-play API's.
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.
5. List your status codes and error messages.
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.
Pro Tip: Providing status and error codes helps not only users of your APIs but also developers and testers alike, as they can be useful for troubleshooting errors and preparing for updates.
6. Write and design for humans.
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?”
Pro Tip: Writing for humans is not always as easy as it may sound, but taking the time to do this not only in your documentation but also within your code (A.K.A. Code Comments) will help immensely.
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.
You can design the user interface (UI) of API documentation from scratch. Or you can use a tool like Postman to simplify the design process.
For the writing, a tool like our free Guide Creator can automatically capture step-by-step instructions as you work through the process.
7. Keep your documentation up-to-date.
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.
Pro Tip: Providing preemptive notifications and alerts about upcoming updates can help users be ready for them and report issues with ease. It can also help to make sure the documentation is maintained properly.
How to Read API Documentation
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.
Dive into a particular method.
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.
Read through a tutorial.
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.
Documenting APIs
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.
![What is Payload? A Quick Guide [+ Examples]](https://www.hubspot.com/hubfs/payload.webp)
