Want to get more people using your app? The quality of API documentation is a massive factor when comparing software providers. And it's often treated as an afterthought. Unsure what we mean by API? Check out our guide to Application Programming Interfaces.
We think we’re pretty good at writing API docs, but we love the opinions of others. So we asked an expert (a technical writer at AWS no less) best practices when writing API docs. Read on and in no time you’ll be writing technical documentation that your users actually want to read.
Let's go.
Documentation is one of the most important yet overlooked aspects of the software development process. Software teams frequently put the majority of their focus on the design and implementation of a particular feature, as they rightly should. However, without a matching focus on API documentation, your software will be difficult to use. This is true even if you manage to create the most efficient, secure, and well-designed API in the world.
API documentation is a central part of the user experience (UX). It’s one of the first things that your customers interact with when using your API. For prospective users, your documentation may be the deciding factor between whether or not they choose to adopt your software.
Writing API documentation can be considered a tedious task, but it’s worth the effort. In this article, you’ll learn what you should focus on when creating API documentation, as well as several tips to keep in mind as you’re writing. These tips are highly coveted by top technical writing professionals, so be sure to begin adopting them in your API documentation today.
Who is your API documentation for?
Before beginning any form of writing, pause for a moment and think about who your audience will be. This can help you decide what to include in your writing and what to focus on. For API documentation, your audience will consist of two types of readers.
1. Existing users
These mainly include software developers who are already using your software. Existing users are typically most concerned with reference documentation, which describes factual information about the system such as API parameters, and procedural documentation, which includes tutorials on how to achieve a certain result. Note that your existing users may have varying levels of experience in the industry, as well as with your API. Your writing needs to be easily understood by all developers even if they are entry-level engineers who are completely new to your product.
2. Prospective users
These can include software developers, product managers, solutions architects, and even C-suite executives. Because prospective users aren’t your customers yet, they likely have some use case for which they need your API to help solve. To help them determine whether your API suits their needs, they are typically most concerned with conceptual documentation describing a particular feature of your product that they’re most interested in. Similar to your existing users, prospective users also have varying levels of experience and technical expertise.
Please note that by nature, API documentation is usually only classified as a type of reference documentation. However, this doesn’t mean that you should leave out types of procedural and conceptual documentation entirely in your API reference. You can incorporate all three types to cater to all members of your audience, which you’ll see in the next section.
What should be covered in API documentation?
Now that you’ve figured out who you’re writing your API documentation for, you can begin scoping out the content. While specifics can vary from guide to guide, all of the best API references always cover the following topics:
Overview of the API
All API documentation should begin with an overview of the API. Oftentimes, this can be very short and sweet since the name of the API should already tell you what the API does. For instance, in the AWS Lambda documentation, the overview for the DeleteAlias API is just a single sentence long.
However, important details should always be called out in your API overview. For example, in the ClickSend documentation for the Forgot Password API, the overview contains a few short paragraphs detailing instructions for use.
Endpoints and methods
REST APIs must include endpoints, which tell developers how to access the resource. Because this is such a key part of your API reference, it often makes sense to make it stand out from the rest of your text. Along with your endpoints, also be sure to include supported methods, such as GET and POST.
API parameters
Your documentation needs to list out all API input parameters. For each parameter, you should include the input type, a short description, accepted values (i.e., Regular Expression [Regex] if applicable), and whether the field is required. You can see in ClickSend’s documentation for the Send Account Verification API that these properties are all clearly listed.
API response
Of course, you should also include the API response. In the ClickSend documentation, this is included in the rightmost panel below the main code samples, as is the case for the Delete Contact API.
Code samples
Upon reading your API documentation, your readers should have no problem invoking your API. Often, the best way to illustrate that is through code samples. As we’ve seen in the previous three examples, ClickSend includes code samples in many major programming languages in the rightmost panel.
Other essentials
Your API documentation should also sufficiently include and describe the following:
- Status codes and exception types thrown
- Authentication methods
- Limits, such as minimum and maximum values for a parameter
- Rate limits, such as maximum API requests a user is allowed to make until they are throttled
- Changelog, or deprecation notices, if applicable
API documentation best practices
To write the best possible API documentation, you need more than just a working knowledge of what to include. Keep the following best practices in mind as you create and update your documentation.
Plan ahead
Before writing anything, it’s always helpful to plan ahead. This means drafting an outline first (yes, this is among the best practices even for documentation writing). With a complete outline, there’s a much lower chance that you forget to include something in your documentation.
Planning ahead may also involve considering the final layout of the docs. You might have tables to organize your input parameters and return values. You might also consider using a two- or three-column layout, both of which are popular formats in the industry today. For example, Stripe’s API documentation contains a three-column layout, similar to ClickSend. As you can see below, ClickSend lists the API actions on the left, the main API description in the middle, and code samples on the right.
The three Cs
Whenever you’re trying to communicate something through your API documentation, you can use the three Cs as writing guidelines:
- Be clear: Technical concepts can get complex very quickly. Above all else, documentation needs to be clear. Aim to write at a sixth grade reading level.
- Be concise: Whenever you can, favor shorter sentences. Make your points direct and simple.
- Be consistent: Your docs should look consistent across all APIs, both in terms of layout and style. Consider adhering to a common style guide if multiple people will be contributing to API documentation.
Avoid technical jargon
You don’t get bonus points for stuffing your docs with technical jargon. In fact, using too many technical terms tends to hurt overall clarity. If you must include a technical term, explain it fully or include a link to more information.
In addition, be careful not to include too many API implementation details in your documentation. This is more common among engineers who also develop the APIs they are documenting. Engineers may feel they have to justify certain decisions by providing certain implementation details. However, users typically only care about how to use your API, not how it’s implemented. Sentences that don’t provide value to the user should be scrapped from your API documentation.
Have sufficient examples
A lack of examples can ruin what would otherwise be a great API reference. Examples can refer to higher-level use cases, where you describe scenarios where a customer might want to use your API.
Examples also mean lower-level code examples that show sample API invocations. You can never have a shortage of code examples in your documentation. Nowadays, it’s customary to provide samples in multiple programming languages: as a baseline, you might include samples in Python, Java, JavaScript, C#, and Go. For example, Pulumi’s API documentation contains code samples in a tablist for most popular languages.
Consider tools like OAS
The OpenAPI Specification (OAS) is a popular tool designed to help you easily generate interactive documentation based on a specification file, which contains your API structures and definitions. You can write this spec file yourself or generate it from code using one of OAS’s many open source integrations. This makes it incredibly easy to onboard, and you can immediately begin creating documentation for your API.
Another reason to consider a tool like OAS is that your API is bound to change over time. In addition to automatically generating code, OAS can also generate new documentation based on any API changes you make.
Gain documentation insights using metrics
As your API reference grows, consider setting up metrics for your public documentation endpoint. This can help you determine which doc pages to prioritize. For example, you can gather data such as page views in order to see which pages are getting the most traffic. You could also consider data points like the bounce rate to figure out whether customers are leaving your docs satisfied with what they read.
Conclusion
A great API has two hallmarks: it is both well designed and well documented. While you should definitely fine-tune API design and implementation, you should also never neglect the importance of writing good API documentation. Documentation is your opportunity to clearly communicate to customers how to use your API. User adoption of your product can be severely affected with poorly written documentation.
Hopefully, this article gave you a good overview of the API documentation process. You started by identifying your target audience and what to include and then learned some documentation best practices you should keep in mind when writing your documentation. By focusing on things like avoiding technical jargon and including sufficient examples, you’re well on your way to producing better API documentation.
If you need to automate parts of your business communications and messaging, consider ClickSend. ClickSend’s APIs are trusted by many prominent businesses to easily send SMS, email, voice, or direct mail to their customers at scale.
About the author
Alexander Yu 🇺🇸 Twitter: @itsxandery
Alexander Yu is a technical writer at AWS by day and a freelance writer by night. After completing his BS in electrical engineering and computer science from UC Berkeley, he became a software developer at AWS for almost three years before transitioning into technical writing. He lives in Seattle with his dog Yuna.
