API documentation is the key to a useful, usable API. An API could be all-powerful, versatile, and entirely useful, yet it won’t matter one bit if users can’t figure out how to make it work. Creating proper API documentation is an artform in-and-of-itself. However, not all coders are good writers, just like not every author is an excellent programmer. Creating useful, informative, understandable API documentation is a skill set all its own.

To help make your APIs more useful, we’re going to share some best practices for API documentation. We’ll start by examining the essential components that every API documentation needs to contain. Then we’ll take a look at some API documentation best practices.

Understanding The Audience For API Documentation

Writers are frequently told to “know your audience.” Who you’re writing for will influence your writing in a variety of ways, from tone to word choice. This is every bit as true for developers creating API documentation.

Very generally speaking, the consumers of API documentation fall into two main categories. There are the decision-makers who decide which APIs to use. Then there are the programmers who will be using the APIs. This means that API documentation needs to fulfill two main functions, simultaneously.

When crafting API documentation, consider: who is the target developer consumer?

You first must illustrate the usefulness of an API to convince the decision-makers. Think about the spec sheet for a product as an example.

The developers who will be using your API are the primary audience you should keep in mind, however. They’ll need detailed, thorough guidelines. This means explaining all of the functions with code samples.

Now that you understand your audience, you should be starting to get an idea of a basic template for creating useful API documentation. Keeping API documentation best practices in mind as you’re developing your API will help keep you in the habit of making notes as you go, helping to compile your API documentation once you’re finished coding.

The Essential Components Of API Documentation

While every API is different, most have some basic building blocks that nearly every API incorporates. Your API documentation should include documentation for these functions, as they’re some of the first things developers will look for when they start to use your API.

Authentication

Authentication is one of the first things a user encounters when using an API. Think of authentication as a key that will unlock your API for your users. Almost every API features some sort of authentication schema, and nearly every one is different.

To start, your API documentation needs to let users know how to access your API. You can take a look at Auth0’s authentication documentation for an example of what thorough, concise authentication documentation looks like.

API Resources

Users need to know what your API can do. List every endpoint with standard commands and responses. Listing all of the commands and responses helps you think like your end-users and create thorough, understandable documentation for each response. Think of it like diagramming your program and then creating documentation for each step.

For example, check out the API documentation for WordPress. WordPress offers a complete and thorough list of all available API endpoints. Each command has its own page, with comprehensive documentation of all of its context, queries, and error codes. Each page has example code, as well, to offer some guidance on how to get started with that particular feature.

WordPress organizes API documentation with a separate page for each function.

In all, this provides a detailed understanding of the API structure. As you can see, there are over 20 resources for retrieving or modifying user info alone. For complex API documentation like this, organization and navigability are key.

WordPress’s API documentation is also an excellent example of usability. Each function features a tag letting you know what HTTP method the command requires, whether ‘GET’ or ‘POST.’ This saves you from having to read each page to have a basic understanding of how to use each API resource.

Error Messages

Debugging is likely to be one of the main reasons people consult API documentation. You’ll want to have a thorough section explaining all of the error messages your API returns. This will make your API more usable for your users, helping them to avoid frustration and have good feelings towards your API.

Don’t limit your API documentation to listing the error messages, either. Include an example or two of how to fix common problems. Check out Mailchimp’s API documentation for an example of thorough, useful error documentation.

From 400 Bad Request to 500 InternalServerError, Mailchimp’s Error Glossary details global errors for the Mailchimp API.

Terms Of Use

Terms of Use are the legal agreement between you and your users. In the Terms of Use section of your API documentation, you should include API limits, constraints, branding guidelines, and what usage is acceptable.

Check out Spotify’s Terms of Service as a model.

Changelog

The Changelog section of your API documentation lets your users know how stable your API is. It also lets them know if anything’s changed, in the instance that one of their calls stops working. You can take a look at GitHub’s changelog for an example of thorough changelog documentation.

Github’s Developer Changelog provides updates on general availability, deprecations, and downtime for various services.

Best Practices For API Documentation

Now that we’ve taken a look at some of the essential components API documentation should have to be ultimately useful, let’s consider some best practices to make your documentation really shine for developers and decision-makers alike.

Avoid Jargon

Remember, you have very little control over who’s going to be consuming your API. There will be users of all different experience levels using your API and reading your API documentation. You want advanced and inexperienced users alike to be able to find both your API and its documentation useful and welcoming.

Excessive jargon is a pitfall that developers may fall into, and it has many drawbacks. First, financial decision-makers often aren’t that technically savvy. If you’re trying to convince them to invest in your API, plain language will go much further than advanced technical jargon.

Secondly and just as importantly, you want your API to be useful for as many programmers, of all skill levels, as possible. If you have to use technical jargon, you should include a link to a glossary, definition, or tutorial explaining that concept in your API documentation.

Sometimes being wordy helps! Take a look at YouTube’s API documentation for an example of thorough, useful documentation written in plain language.

Thoroughly Document ALL Requests and Responses

There’s no such thing as too much information in API documentation. Users aren’t likely to read the whole thing in one sitting anyway. When a user is just starting out with your API, they’ll likely need a bit of handholding until they’ve integrated it into their workflow.

With that in mind, you should include documentation of every call your API can receive and provide some context for both the parameters and responses. Also document the responses as they’ll let your users know things are working as they should. Document every potential error message, as well. This is all towards the goal of letting your users see exactly what will be returned from an API request. This will spare them the trouble of having to turn to Google to troubleshoot if something goes wrong.

Include Additional Resources

If something is outside of the scope of your API documentation, you should include links to the necessary information for your users. Again, you don’t want your users to have to seek answers via a search engine, which can be frustrating and leave them with a negative association towards your API.

Include A Getting Started Guide

You want users to be able to get up and running with your API as quickly as possible, so they can see how useful it is. A quick guide on how to get started using your API is the easiest way to make this happen.

You can take a look at Braintree’s Getting Started documentation for an example of an excellent Getting Started guide.

Include Sample Code

The fastest and easiest way to get a new user up and running with your API is to include some sample code in your documentation. The user simply needs to replace the API key in the sample code with their own key and they’re off and running.

Sample code also gives developers a chance to see finished code implementing your API that they can reverse engineer and pattern their own programs after. You might consider having documentation for each individual section and then have sample code at the end showing all of the functions at work.

Best Practices For API Documentation: Final Thoughts

Good API documentation is the foundation of quality developer experience. It’s what separates your API from being usable and useful from being frustrating and inessential. What good is your API if no one knows how to use it? How should users know to invest time, energy, or resources let alone money if you’re releasing a commercial API if they don’t know what your API does or how it can benefit their business.

Having good API documentation often means the difference between a recommendation or a negative review, as well. You want users to be glowing about your API, singing your praises to their network and community. Good API documentation is one of the most essential ways you can make that happen, offering useful information, clear instructions, and easy-to-follow examples.