If you’re currently creating an API product, you’ll have to work hard to ensure that customers notice and adopt your software instead of your competitors’ products.
Since API documentation is often a reason why people purchase or abandon the API, companies with polished API docs stand better chances on the market. We got your back with our API Documentation examples you should read in order to understand the full concept.
So, if you want to help your customers use your API effectively and simultaneously gain their loyalty, your API documents, which represent a very important type of software documentation, have to be informative and contain all the crucial elements.
This article will explore the eight elements all API docs should have in order to assist customers while they’re building their own solutions.
First up is the introduction to your API, the overview section.
Overview Section
Just like you’d preface any piece of technical writing with a foreword, your API documentation deserves a proper introduction. In that order, we wrote two very powerful article, the first one about various types of technical writing you should definitely know about, and in the other one we gave few tips for writing great API documentation.
A sleek overview section should be the first element your readers see so that they know what to expect from the API.
The overview shouldn’t cover the details of how the API works under the hub—there’s room for that in other document elements.
Instead, it should briefly describe the product and its purpose. Here’s an excellent example from Kornia, an image processing library.
As the screenshot shows, Kornia has a brief overview section that consists of two elements. It describes what the solution is and why developers should use it.
And that’s it; enough content to make a striking first impression without cluttering the docs.
An additional section showcases the features that separate the library from the others.
The examples of images processed with the library demonstrate its capabilities even better than the written description.
However, it’s important not to overcrowd the overview section of your API documents and focus only on the leading ideas behind the API.
Listing the API’s selling points, as a good support for sales, allows the users to make their purchase decisions quickly without digging deep to find if the API suits their needs.
If you want to go the extra mile, you could also incorporate a quick-start option to your API.
After you’ve captured the users’ attention with a well-written overview, why not make it easier for them to onboard the API immediately?
A concise installation guide can help customers start using the API frictionlessly, so consider including one in the introduction to your API docs.
Universal API Resources
After you’ve told the users what your API can do for them, it’s time to provide them with the tools to implement the solution. Here's a general vision on different tools for documenting your APIs.
Universal API elements, such as API’s endpoints, parameters, and request and response examples, will equip your users with all they need to work with the API successfully.
Now, think of the last piece of API documentation you’ve seen. And the one before that. That’s right—almost all API documents contain the same essential elements.
Let’s analyze an excerpt from Mailchimp’s Marketing API documents as an example.
As the screenshot shows, each route comes with a brief description and a list of parameters.
Ready-made and copy-pastable code samples allow the users to try the API instantly or tinker with it further.
Mailchimp also offers code samples in multiple programming languages to remove the potential friction in the development process.
Of course, no matter how practical your API is, you should still plan for bugs and errors. That’s why error handling is an essential element of API documentation.
You can address errors with error responses. Another popular method of error handling is to create a list of standard error codes, as Mailchimp does.
Developers can use the list to find additional information for specific errors.
All in all, the standard API resources are why people visit documentation pages.
If you want to grant them a smooth developer experience, you should make sure that your API resources are clean and always up-to-date.
Tutorials
Step-by-step tutorials are amazing resources that straightforwardly tell your users how to implement a solution.
If you’re aiming to make your API documentation as clear as possible, then tutorials are a must-have element.
However, tutorials are only helpful if they’re designed right. If you need a good role model for constructing API tutorials, Stripe’s documentation is a good place to look.
Stripe’s tutorials begin with an overview of the steps the user has to take, organized as a clickable table of contents.
The overview of steps allows users to skip to the parts they need. Still, those who decide to follow the exact steps can find a more detailed description of each action.
You should keep in mind that the crucial element that determines the success of your tutorials is the amount of information presented.
Each step should contain only the information the user needs at that specific point.
Adding optional details clutters the tutorial and makes it less helpful, so make sure you stick to the essentials.
For instance, here’s the second step from the Stripe payments tutorial we’ve just seen.
The tutorial shows users the exact actions they need to take, along with code samples and alternative configuration options.
While Stripe has planned for various alterations to the process, you won’t find these optional steps in the middle of the tutorial.
Instead, all the optional steps are outlined in a separate section at the bottom of the main document, preserving the clear structure of the content.
Glossary
There’s no such thing as too much clarity in API documentation—the readers should always understand what you’re referring to.
You can boost the readability of your API docs by compiling a glossary of specialized terms.
If writing a glossary from scratch sounds excessive, this horror story from Kin Lane—known as the API Evangelist—might change your mind.
Lane was reading API documents and encountered an unexplained acronym. The document described DEGs in detail; how you could add, update, and delete DEGs and pull their analytics.
However, the definition of a DEG was nowhere to be found.
“I spent about 10-15 minutes looking around their developer portal, documentation, and even Googling, but never could figure out what a DEG was. Nowhere in their documentation did they ever tell consumers what a DEG was, you just had to be in the know.”
So, if you’d like to avoid confusing your readers like that, you should create a glossary explaining the terms unique to your product and other items of specialized vocabulary that your average consumer may not understand.
Here’s how Apigee does that.
Apigee’s API glossary goes beyond acronyms; it also explains the concepts that have a unique meaning within the platform.
That’s the right approach to API glossaries; you don’t have to define the terms that are common knowledge within your domain.
For instance, there’s no need to define adb (Android Debug Bridge) with a sample Android app because your readers are probably already familiar with it.
On the other hand, if your API uses many original or specialized terms, a glossary should be among the elements to add to your documentation.
Examples
Besides describing technical details, your API docs should also cover the examples and use cases that illustrate how the API works.
The best way we can approach the subject of API examples is by examining one, so we’ll look at how Twitter demonstrates possibilities that developers get by using the Twitter API.
When you first open Twitter’s developer platform, you can immediately see several categories of the API use cases.
These broad use cases give readers a general idea of how they could enrich their applications and websites with the Twitter API.
Clicking one of the categories shows you more precise possibilities. For instance, readers can learn that they can embed Tweets into their websites and articles.
That way, they can promote their own Twitter content or display other people’s thoughts.
Either way, embedded Tweets help make websites more interactive, which is a quality that most companies strive for.
After you’ve outlined several examples of how your API can benefit the customer, it’s vital to equip them with the tools for implementing the API.
In other words, you have to create code examples or recipes that developers can try out.
For instance, Twitter has created an HTML and JavaScript example that devs can use to implement the embedded Tweets feature we’ve mentioned above.
To sum up, the best way to present your product and its API is to tell the users about the real-life uses for it.
Once you’ve shown how your API benefits the users, you also have to provide them with code examples so that they can quickly try out the solution for themselves.
Creating these examples could take some time. Still, they are a valuable element of API documentation that is bound to increase customer acquisition.
Changelog
As your API improves over time, its documentation should evolve along.
To inform your customers of changes to the API, your documentation should contain the changelog as one of the essential elements.
Changelogs are an excellent way to show how your product evolves. You’ll notice that most changelogs divide changes into categories such as improvements, modifications, and additions.
However, parts of APIs sometimes get removed or decommissioned. That’s the reason why it’s also vital to highlight deprecations in your changelog.
Without noting deprecations, customers using an existing API could experience calls that have stopped working and not know the reason nor the solution, as this Twitter user experienced.
In such cases, a changelog explaining how the change impacts the software and how customers can continue using the changed feature keeps the API usable.
Some companies go a step beyond updating the changelog and even offer to notify the customers of API changes.
While such a proactive approach certainly keeps users in the loop, it may also overwhelm them with notifications unrelated to their app.
Therefore, including a changelog in your API documentation is a safe way to help users adapt to the new API, maintain their apps, and continue using your API to its full potential.
Limitations
Customers demand transparency from vendors and businesses of all kinds, API providers included.
To present your API transparently, your documentation should describe the API’s limitations. This lets users know what the API is capable of, ensuring realistic expectations.
The following image shows how Salesforce, a CRM platform, describes the limits and allocations of its API.
As you can see, the guide lists the limits of specific parts of the API shown on the left.
The most common way to present API limitations is by stating the rate limits. API rate limits control the number of requests a user can send or receive within a given time period.
The limits help prevent the API from being intentionally or accidentally abused.
For instance, if your API rises in popularity, the unexpected spikes in traffic may cause severe lag time, leading to the end users’ dissatisfaction.
Because of that, it’s important to be upfront about rate limits and specify the exact rate in the document, as Salesforce does here.
Apart from mentioning rate limits, this element of API documentation should also state if there are any other constraints to the API that happen due to privacy concerns, the scope of the API, or simply due to what’s technically possible.
For example, the Salesforce documentation also lists the limitations regarding the file size and number.
So, if you want the users to form realistic expectations of the API, you have to be clear about its limitations.
The limits are often described within terms of service, our next API document element.
Terms of Service
If you want to ensure that customers use your API properly, you should create a document listing the terms of service (or use).
Here’s the beginning of one such document designed by Tallyfy, a workflow management platform.
That legal agreement between the company and the users establishes the conditions under which they can use the API.
However, it’s also common for terms of service to elaborate on API limits and branding guidelines.
Defining all these rules helps you guarantee that the users employ your API in the best way possible.
For instance, Tallyfy’s API terms of service prevent users from using the API to promote gambling, ensuring that the API is always seen in a good light.
The terms also warn the users about the potential changes to the API that may occur during the development process.
Your terms of service will vary depending on the type of API you’re providing. Still, you can use this list of common elements to get started:
- API definitions
- API license
- Data storage
- Privacy policy
- Security measures
- Ownership
- Dispute resolution
Unlike other elements of API documentation, the terms of service document probably isn’t a type of document your in-house technical writer can create independently. We have for you a good answer for the question ''What does it mean to be an API technical writer?''.
For best results, you should contact a lawyer of a legal firm specializing in the tech industry. Here's a quick example of how a ''Terms Of Service'' page should look like. Yes, it's our page of terms of service :)
Conclusion
When you combine the eight elements we’ve analyzed, you’ll be able to create holistic, comprehensive API documentation that answers all your users’ questions even before they ask them.
Such an informative knowledge base will ultimately reinforce your position in the API market, bringing you new customers and the funds you need to keep improving the API.
So, once you finish outlining your API docs, feel free to refer to this list to make sure you’ve included all the vital elements.
In conclusion, with this article, Archbee provides a comprehensive overview of the essential components that should be included in any API documentation. From endpoint descriptions and request/response formats to error handling and authentication protocols, each element plays a crucial role in helping developers understand and utilize an API effectively.
Always take care that you use these elements and make sure that no api document should be without. By following these guidelines of and including these crucial elements in their documentation, API providers can ensure that their users have the information they need to integrate their software seamlessly.
