Best Practices for Your API Documentation

Susanne Lundkvist
Sep 14, 2019 · 4 min read

As a developer connecting to a new API, the documentation can make all the difference. Here are some best practices for API documentation that should make it easier for anyone connecting to it.

Who Is Your Target Audience?

As with all types of communication, the first thing is to decide who you are writing it for. API documentation is of course written for developers but not exclusively. There could be plenty of other stakeholders that will read it to understand and decide on whether to go ahead and adopt it. You will have to cater for developers, product/project managers and other key stakeholders when writing your API documentation.

It is a common mistake to assume all readers are very technical and use technical jargon. You should write in a way that can be easily understood by people who are new to the API or industry. If you have very specific technical terms you can link to further explanations of those.

How Will It Be Maintained?

Another question that you need to ask yourself early on is how the documentation will be maintained. It doesn’t matter how well you document your API if the documentation will not be kept up-to-date. Make sure to have an agreed process in place for updating and keeping the information current.

Are You Using A Tool?

There are quite a few tools for writing APIs in the market. RAML, Swagger and API Blueprint have open source communities offering pre-built documentation tools you can use. And here are a few more to choose from.

Tutorials and Examples

Consider making some tutorials to explain the basics of your API in the form of videos. It is often much easier to follow a video tutorial than reading up on lengthy documentation. It is also a great way for developers to get started quickly. After having set up the basics and make it work, a developer is more inclined to look for additional answers in your written documentation.

Give plenty of examples throughout your API documentation. It makes it much easier to understand what to expect.

Console or Sandbox

You can encourage prospects to immediately test what they read in the API documentation with the API console. To provide a console or sandbox environment can be a relatively simple effort to allow users to interact with your API and experiment to understand the value you are providing. It is also a great way to get started.

Essential Content


Most APIs have authentication schemes, and developers have to authenticate before gaining access to the API. Make sure you go through every single step for authentication in detail as this is the threshold to get access and the integration won’t go any further without it.

Terms of Use

The legal agreement between the person consuming your API and your organisation defines how the user should ideally use your services. Include API limits under best practices. The constraints should also be clearly stated so that users understand the practices permitted.

Getting Started

A Getting Started section should provide a detailed description of how to quickly start working with your API. The emphasis should be on making sure users can be successful with your API as quickly as possible. A Getting Started video tutorial is worth considering (see Tutorials above).


List all of the resources your API exposes, and make sure you understand how users may integrate with them. This will help document the requests and responses under these resources.

Requests and Responses

Document every call your API offers, with context around the parameters and responses. Responses are the guides for your users, indicating whether they’re on the right track, or providing guidance with error messages to help them succeed. Your API users should know exactly what to expect from a successful API call. Describe the full sample response body in every supported format. Think of not only the format, like XML or JSON, but also of HTTP headers, error codes, and messages.

Error Messages

Explain your error standards and provide solutions on how to overcome them when an end user gets an error. Detail all your possible error codes that users may receive.

Change Log

Your documentation needs to have a change log, detailing updates and versions of your APIs and how that might affect API users. This will help them understand the stability of your API and see if any changes need to be made on their side for an effective API call.

Susanne Lundkvist

Susanne Lundkvist

Written by

Product and Programme Manager, currently coding in Ruby on Rails, JavaScript and React. Improving project management with personal apps and data analytics.

More From Medium

Also tagged Tutorial

Also tagged Tutorial

DATE/TIME Functions in SQL

Top on Medium

Ed Yong
Mar 25 · 22 min read


Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade