3 Best Practices for API Documentation

By 
Elizabeth Garcia

What is API Documentation?

API documentation explains to API users and developers what is possible with your API and how to use it. API documentation generally includes descriptions of your API functionality, references, instructions for implementation, and use case examples.

At the minimum your API documentation should answer two questions: 

  1. What is possible to accomplish with this API? 
  2. How do I get started? 

Why is API Documentation Important? 

API documentation is where API users and developers go to learn about your API and how it works. Thorough and easy-to-follow API documentation leads to higher adoption and a better developer experience (DX).

Companies understand the importance of design thinking around user experience, and how it can contribute to customer loyalty and retention. DX is equally important to API adoption and a well-thought-out DX will similarly increase customer and partner loyalty.

API documentation is key to the developer experience. Developers usually prefer to self-serve and excellent API documentation enables them to efficiently plan and build their integrations, without having to reach out for support.

It also prevents hidden surprises halfway through the build process where developers discover your API doesn’t enable a use case they need or has limits that need to be worked around. 

SmartBear, who built Swagger, surveyed developers and users of APIs in 2020. When asked what are the top three most important characteristics they need in an API, accurate and detailed documentation beat out responsiveness/performance.

Poor API documentation will impact implementation speed, increase costs, and make development teams unhappy. With more organizations offering digital services, API consumers have more options to choose from. If your API is for customer or partner use, a poor DX can damage your brand reputation and push customers and partners towards products that are more developer-friendly.

Best Practices - What Makes for Good API Documentation and Developer User Experience? 

  • Be clear on who your audience is. 
  • Include sections and resources API users and developers need to be successful. 
  • Have a process for updating documentation and notifying third-party developers. 
Be Clear on Your Audience 

Your audience can range from developers and CTOs to product managers and non-technical customer support or business teams. Being clear on who your audience is enables you to make more informed decisions about how to make your documentation accessible, the kind of sections you should include, what language to use, and how to structure your documentation. 

For example, your API may be for partner use only, or for internal use only. Other times, it might be only for enterprise customers. Whoever your audience, you should ensure there is a clear path for them to locate documentation and that proper access is granted. 

Some API providers like Google include a blurb at the top of their API documentation that describes the audience it is targeted to, including what technical knowledge they will need and links for further research. 

Not all API documentation is designed only for developers. Some documentation can be understood by product managers and even business users looking to see what is possible to accomplish with a particular API. 

Like Google, it is helpful to provide the information upfront on who a particular set of documentation is for and what knowledge is required to understand it.

Include Sections and Resources that API Users and Developers Look For 

SmartBear, who built Swagger, surveyed developers and users of APIs in 2019. They asked what features and sections developers look for in API documentation. 

The responses illuminate what categories you should be investing in documenting first, and what categories you should aim to include as your documentation becomes more mature. 

Results from SmartBear's 2019 State of APIs survey asking API users and developers what features they look for most in API documentation.

Let’s take a look at some of the most important sections to include in your documentation.

API Overview 

While this section wasn’t a part of the SmartBear survey, this section is key to ensuring the right people are reading your documentation and that they have the right expectations.  

Use an “API Overview” section to give your audience clarity and hook their attention into reading the rest of your documentation. Remember, especially when an API is being considered by a customer and a partner, you want to encourage adoption and keep people from dropping off. Third-party developers may have no idea what capabilities your API offers, and you want them to excite them enough that they take a more serious look. 

Here is an example from Facebook describing how their Instagram API can be used, for example. Google also has a page that lists the most common use cases for their Google Maps API and includes links to documentation for APIs that best suit those needs. 

Examples 

This was the number one section that API users look for when reading API documentation. Remember many users will be completely unfamiliar with your API, and examples are the quickest way to illuminate what is possible.

Providing snippets of code that developers can easily copy and paste, with examples in context, can allow for easy adoption, limited questions, and less troubleshooting on your end. Twilio, for example, details example error responses and what might trigger them.

Some APIs, like the Deezer API, go beyond laying out examples and even allow developers to test endpoints with interactive demos. 

Status and Errors 

Developers need to know what errors they might get and what each error means.  List any errors that can be returned by your API with readable descriptions. 

Many companies’ API documentation has a page specifically dedicated to error messages. Some companies also include error messages and descriptions under endpoints where they tend to happen the most, which is useful when building an integration. 

They can also be included as part of a troubleshooting section at the end of a quick-start guide. 

Authentication 

Since authentication is one of the first challenges of getting started with an API, your documentation should clearly outline how authentication is handled for your API. 

For example, if your API requires the developer to get an API key to authenticate, you should specify how one can get an API key, how the key works for making requests, and how to restrict API keys. 

Whatever your authentication scheme (what is required for the authentication process for your API) ensure that you clearly document and list out steps for how users need to authenticate before gaining access to your API. 

Slack, for example, uses OAuth 2.0 authentication to allow end-users to download API consumer apps from slack workspaces. See here for an example of their authentication documentation. 

HTTP Requests 


HTTP is a protocol for requests sent to a server. It identifies what actions (known as methods) that can be taken through your API and on which endpoints. In your documentation, you should clearly lay out all the available methods and their endpoints.

Two of the most common HTTP methods are GET and POST. GET requests are used for receiving specific data fields, while POST requests are used to update or create new data fields in your system. 

Specify the type of requests you are enabling, and what fields the request can apply to, to improve your developer experience. See an example of how Hubspot organizes this information this below. 


Have a Process for Updating Documentation and Notifying Developers of Changes 

APIs change faster than ever, and outdated API documentation is one of the major ways developers and users end up having a bad experience.

Put in place an internal process for ensuring that API docs are updated whenever changes are made. This can be folded into your product update process, or even assigned to someone who will be notified whenever changes are made.

If your documentation is extensive, one way to ensure you’re updating the most important parts of your documentation is to use tracking analytics to determine what endpoints are used most often so that you can prioritize updating those first.

Some of the most popular tools for API documentation include Slate and Swagger. Swagger in particular offers many solutions for creating and maintaining your documentation so that it stays up to date. They also provide resources geared towards improving developer experiences like Swagger Editor and SwaggerHub that provide a YAML editor with a visualization panel. This allows developers to work in and see how your API will look and behave before they actually implement it

Slate is an open-sourced, free tool that allows you to create a clean and intuitive design. It allows you to create a three-panel webpage, one panel for navigation, another for documentation, and one for code samples. See more examples of documentation created using Slate in their repository. 

In addition to updating your API documentation, ensure developers are notified and made aware of these changes. Most companies have a developer email list that they send notifications of changes to as well as a developer-focused webpage where upcoming and current changes are noted.

Conclusion 

Invest in understanding the audiences for your API and how the audiences intend to use it. Creating API documentation that enables an exceptional user experience will increase adoption, limit delays and problems, and ultimately improve your brand reputation and customer retention. Lastly, treat API documentation as part of your API. Ensure it is thorough, accessible, and up to date so that your API users are able to have the best possible experience.  

Keep up with Pandium

We regularly create quality content on how to leverage tech partnerships and integrations to grow. Subscribe to our bi-monthly newsletter so you don’t miss any of it.
Keep up with Pandium by subscribing to our newsletter