The intended audience of API documentation are developers who need to simultaneously learn about the API and understand how to use it in their work.
As such, it needs to contain both descriptive and practical code-based elements to really be valuable to its users.
This checklist covers both elements, as well as some handy optimization and sharing practices for API documentation.
By ticking some, or most, of the boxes on this list, you should be left with a well-rounded API knowledge base developers will love coming back to.
Let’s start at the very beginning.
General Overview
Starting an API document with a general overview section is always a good idea, so make sure you’ve included one in every article. Here's a few types of API documentation to know about!
We’ve seen a lot of documentation that dives straight into the code, preferring not to waste the user’s time with introductions and overviews.
But this could have the opposite effect.
It’s quite possible for users to waste enormous amounts of time exploring the wrong documentation because there isn’t an introductory section to tell them what lies ahead.
To avoid the frustrating situation in our above example, try to do a good job providing a general overview of the document you’re writing.
Here’s how Stripe does it:
Stripe’s documents always start with a short introduction explaining exactly what the action, object, or resource in the documentation does.
It provides an explanation of the topic of the document and tells the reader what they will be able to achieve once they follow the guide.
After reading this section, the user knows if this is the information they were looking for or if they need to keep searching.
This section should take you just a few minutes to write but it’s incredibly useful to users, so make sure each document has a general overview right at the top.
Getting Started Guide
Every activity has a starting point or a way to begin and working with APIs is no different.
To show your users how the API works, you need to give them the first steps in the form of a Getting Started guide.
Here’s a quick example GraphQL’s API Guide:
This is a very typical, developer-friendly way to help users get started.
There’s a quick introduction followed by a description of the way to install or launch the product or feature or action (depending on the document).
In this case, the user can get started by copying and using a piece of code that will launch a GraphQL server.
The guide then continues with the other steps the user should take to successfully install and use the product. You can see what those steps are in the menu on the left-hand side.
Providing this kind of fast launch option allows the user to quickly and easily immerse themself in the API and keeps them engaged because they’re doing much more than just reading documentation.
They’re actually using the product in parallel to learning how it works.
The point here is that providing a getting started guide makes your documentation more engaging and interactive for users.
That means users are much more likely to keep reading the documentation and, by extension, find success using your API.
Developer Fundamentals
In addition to an overview and a starting guide, another introductory element to include in your API documentation are the developer fundamentals.
These are the basic functioning parameters of the API and they need to be described thoroughly in order for the API to be used correctly and without problems.
Here are some developer fundamentals you might consider including in your documentation:
- Error codes
- Authentication
- Rate limits
- Terms of use
- Changelog
- URI (endpoint)
Having these elements included in the documentation makes it extremely valuable to developers and works as a sort of reference to help them work faster and more efficiently.
Take error codes, for example. Developers working with the API are likely to encounter errors along the way.
In that case, if error codes are available in the documentation, the developer can simply look up the error to find out what’s happening.
We’re using Twiilio’s API and documentation for this example.
And if the API documentation is really exhaustive, it will also propose some possible causes and steps to fix the error in the shortest time possible.
Remember, API documentation is all about providing users with practical tools and actionable advice to make working with your API a breeze.
A developer fundamentals section is a must if you want to provide a quick and practical reference developers will keep coming back to.
Description Section
It’s true that developers prefer to dive straight into the code and try everything out for themselves, which means API documentation is a type of technical documentation that isn’t very text rich and relies more on code to get its point across.
Nevertheless, API documentation is used by actual people, meaning it needs to provide guidance in textual form, as well as code.
Therefore, while you’re checking your documentation, don’t forget to confirm that things like parameters, endpoints, calls, and authentication methods are described in detail.
Authentication is a great case in point here. There’s a variety of ways to authenticate API requests, so it’s crucial to be very specific in explaining your methodology to users.
For example, GitHub has a very detailed explanation of the basics of authentication that users can read through in order to understand the ins and outs of the authentication process for their REST API.
As for other elements, such as parameters, don’t hesitate to repeat yourself.
Even when very similar calls are concerned, the full description needs to be present every time because your users won’t be reading the entire documentation, but rather specific articles that interest them.
To make a long story short, your API documentation isn’t ready for publishing until each document and article is supplemented with a proper description.
Code Samples
Now we’re coming to the fun part, at least as far as your developer users are concerned.
Code samples are the element of your API documentation that shows developers how to accomplish different things and respond to a variety of scenarios.
That’s why, as a rule of thumb, you should provide code samples at every possible opportunity, especially in documents guiding users through the more complex and sophisticated workflows.
Trust us, your users will love you for it.
Even better, trust the data. Twilio has studied their own documentation to see what kinds of documents their users prefer.
As it turns out, developers stay on the page for longer when code samples are introduced sooner rather than later.
Shopify’s API documentation implements this lesson well.
Their documentation is full of code samples that allow developers to do almost anything within the scope of the API, like retrieving a customer’s information.
As you can see, the documentation wastes little time providing the user with the code they can use right away.
That last point is very important. If you’re going to provide code samples, you want users to be able to implement them without delay.
The best way to do this is to enable users to copy and paste the sample straight into their own application.
If you’re writing your documentation in quality documentation software, such as Archbee, this should be easy to do as this kind of software enables you to input code and make it readily available.
Code samples make API documentation interactive and actionable, so don’t forget to include as many as you can while you’re guiding users through the API.
Examples in Different Programming Languages
As long as we’re on the topic of samples and examples, it’s worth noting that developers can use practically any programming language when working with APIs to create requests.
That means you should do your best to provide examples in multiple programming languages.
That way, you’ll be sure your documentation helps the largest possible number of developers who turn to your API documentation in search of guidance and quick solutions.
For instance, MailChimp’s API documentation provides code samples in five languages. Users are free to hand-select which language they want the code to be presented in.
Once again, this kind of support is only possible if you’re creating your documentation in modern documentation software.
Archbee has a multi-language editor that allows documentation writers to input code in different languages and organize the same example according to programming language using handy tabs.
By doing this, the user instantly sees which languages are available for this example and can switch between them effortlessly, should they need a comparison, or different versions of the sample code for their work.
Keep in mind that your API users will be working with different applications and don’t forget to check that every piece of code you’re providing is available in all the languages you want to offer in your documentation.
HTTP Methods
HTTP request methods are an integral part of working with APIs. They are used to structure requests and responses when a client communicates with a server.
There are multiple HTTP request methods that do different things, so it’s a good idea to provide a quick reference to them in your documentation and explain how they work with your API.
Let’s revisit Shopify’s API documentation to see how they handled HTTP methods in their documentation.
There are a couple of great practices to note here. First, every type of request is quickly described, providing clarity to the user on what it is that the request does.
For example, a POST request is used to create a new product.
Secondly, and this ties in nicely with our previous section on code samples, each request method is supplemented with an example that allows the user to see the request in action.
HTTP request methods are standard stuff, but no API documentation should skip explaining their methods as they are applied to their specific product.
Tutorials for Common Use Cases
When reviewing your documentation, take the opportunity to check if you’ve included enough educational content for your users.
In most cases, this means step-by-step tutorials that cover common use cases for your API.
Tutorials are a great way to show users everything that can be achieved using the product and help developers go above and beyond with your API, so it’s definitely worth the effort to provide them as a part of your API documentation.
Twitter’s API is actually quite famous for providing tutorials for any use case developers can think of.
Providing this wealth of resources, Twitter’s API documentation helps developers learn about the API through practice and use, while at the same time giving them new ideas on how to implement the API into their own work.
Here’s an interesting tutorial on how to analyze the overall sentiment on individual tweets.
If you don’t know where to begin, just brainstorm the common uses of your API and then provide a tutorial for each one.
Don’t forget, the key to a successful tutorial is providing enough details.
Break the process you’re trying to present into as many steps as possible and put them into sequential order.
If possible, provide visual aids and screenshots to show the user how every step of the process works.
And before you know it, you’ll have a helpful, easy-to-follow tutorial for even the most complex use cases for your API.
API Explorer
Another developer-friendly resource to have in your documentation is the API explorer.
This interactive feature allows developers to run simulations of various actions that can be done using the API before they implement them into their own products.
The value of this should be obvious. An API explorer presents developers with a way to test out the API, without consequences for their product.
They can simulate all of the responses from the API and see exactly how it will integrate with their application.
Google’s API Explorer has one of the most exhaustive directories of APIs developers can try out to see what kind of responses they can get.
All a developer needs to do is search for the API they want to explore within the documentation and then select the method to try out.
For example, here’s Google’s API for abusive experience reports for pages. The method selected is GET.
The user can then read about the action and, once they’re ready, they can try it out through a window that pops up on the right-hand side.
The environment where an API is tested within the documentation in this way is sometimes called a sandbox, emphasizing the fact that this is a place for developers to play and build with the API, without having to integrate the API into the application they’re working on.
So if your documentation doesn’t have this feature, consider if you have the resources and time to add it as it will definitely be appreciated.
Documentation Optimization
The last item on this checklist addresses usability, user experience, and shareability.
In these matters, API documentation is similar to a lot of other types of online content, meaning you can improve your documentation by applying some good old-fashioned SEO.
SEO practices in documentation mostly have to do with URLs, as well as using titles and subtitles to make your documents shareable and easily searchable.
As far as URLs are concerned, all you need to do is make them descriptive so that the user can discern what the document is about, just by looking at their address bar.
This has the added benefit that it makes the online document easy to bookmark and share because the title of the page will be instantly recognizable to the user.
Even more importantly, you should check how your API documents are structured. Are the articles properly titled and divided into subsections, each starting with the correct subtitle?
This kind of organization helps users navigate the page. It makes all the information easily scannable, so users can find what they’re looking for faster than they would on a disorganized page.
Plus, dividing your content into sections and subsections allows you to build navigational menus, like the one on the left-hand side in our example above.
That makes jumping between pages in the documentation almost effortless and provides everything the developer needs at their fingertips.
SEO practices have been around for a long time. It’s true that their primary goal is to help search engines recognize and rank your content, but that’s only half of the benefits.
The other half has to do with providing an excellent user experience for content consumers, meaning that these principles are definitely applicable to all sorts of technical documentation, including API documents.
Conclusion
Having gone through this API documentation checklist, you should now have all the elements needed for a highly usable and extremely helpful API knowledge base.
Remember, API documentation is created for developers, so make sure your documentation contains both textual and interactive, code-based elements to help users learn about your API and use it successfully.
And don’t forget to confirm that every article in your documentation can be accessed by the right people exactly when they need it.
‍
