There’s a popular saying that goes: “an API is only as good as its documentation.”
Unfortunately, the complexity and the lack of documentation are common obstacles to consuming APIs.
So, it’s not enough to ask a developer to whip up a doc; the documentation has to be informative and readable.
If you’ve been wondering how to create the best API documentation possible, you’re in the right place.
We’ll examine the best practices for writing API documentation and see how you can create an effective documentation base that helps your team use and integrate the API effectively.
Determine the Users of Your API Documentation
Identifying the users of your API documentation may sound simple enough, especially if your aim is to organize internal documentation.
Still, you should keep in mind that developers of various specializations work with the documentation and adapt it accordingly.
BJ Rutledge, a software engineer at Iconitek, wrote a post on LinkedIn discussing the importance of API documentation.
One of the pieces of advice Rutledge provided was to “take the time to think about the reader.”
One way to interpret the advice would be to think about different writing styles for multiple expertise levels.
For instance, if you know a lot of junior engineers will read your API documentation, you could focus on tutorials, samples, and guides.
On the other hand, if seniors are the primary users, it’s more helpful to include syntax, arguments, and response details.
However, adjusting the writing to the seniority levels is not the only approach. You could also ask API writers to consider their peers of different specializations.
We’ll take an excerpt from GitHub’s REST API documentation as an example here.
GitHub uses the OAuth2 standard as a part of its API. Chances are that a back-end developer wrote GitHub’s documentation.
In that case, the author could have stopped at writing that the company used OAuth2 for online authorization. All other back-end and full-stack developers would understand the meaning.
Yet, not all readers have the same background, even if they are software engineers.
This is why the documentation about OAuth2 includes links that help mobile and all other developers understand the standard if they ever need to use it.
To sum up, your team may consist of brilliant developers, but you still need to think about who specifically will read the API documentation while working on the product.
When in doubt, the best practice is to start the documentation at the basic level. Read on to see how.
Write for the Entry-Level User
Writing internal API documentation in a way that’s accessible to entry-level users doesn’t mean you’re underestimating your developers.
On the contrary, documentation that’s straightforward and easy to understand allows them to quickly figure out the API and start using it with ease.
A common piece of advice is to write external API documentation for the entry-level user so that readers from different audiences can understand it.
For instance, you want journalists who may not have the technical knowledge to be able to write about your company.
Similarly, clear API documentation will allow CTOs or solution architects from other businesses to quickly decide whether your API is a good fit for them.
However, a comprehensive internal API documentation is as important.
We’ll now look at HubSpot’s CRM API documentation to see how the company has presented it, clearly and concisely.
As you can see, there’s the description of the API immediately below the heading—no room for speculating what the section is about.
Next, you can find a code example so that developers can see a representative application of the API.
Lastly, there’s a list of pseudo-property values that allows the developers to see which values they can expect to get from a request.
Note how HubSpot achieved clarity by keeping the information succinct rather than providing convoluted explanations.
According to Slava Fioletov, CIO of a software testing company, keeping the information concise is one of the best practices when it comes to software documentation.
“Remember, the documentation doesn't have to be lengthy. Its task is to provide a comprehensive description of the project in a simple and understandable language.”
Another tip we have for writing for entry-level users is to avoid overusing jargon.
If you tasked your devs with writing API documentation, you’d probably end up with high-level documents laden with jargon because they’d assume that every team member has the same knowledge.
However, since everybody from juniors to seasoned developers should be able to understand your API documentation, you can overcome this challenge by hiring tech writers or API writers to bring clarity to documentation.
Your devs can provide code examples, but it’s a good idea to also hire a more objective person to make sure the documents are genuinely easy to get through.
Create by Using an Industry-Standardized Layout
In the same way that you encourage your in-house development team to stick to consistent coding practices, you could reciprocate by using an industry-standard API documentation layout.
The practice of standardizing the layout is the best way to help your developers navigate through the API documentation effortlessly.
While a list of classes and functions does contain the material helpful to those trying to understand the API, such a format is by no means intuitive or easy to maneuver.
We’ll take a look at OpenCV’s API documentation as an example.
The page you see above lists classes. You can also find some functions, but no explanation or context is provided.
If your API documentation looks something like this, it is probably challenging for your developers to find the needed information, even if it were there.
A better approach would be to research the industry-standard API documentation layouts and model your documentation after them.
For instance, if you’re building documentation for an iOS API, it would be best to scan Apple’s API documentation.
Noticing the common patterns in how documentation is organized will help you mimic the layout in your documentation base.
The documentation that you can see in the image above was generated using the DocC library.
Since iOS developers are accustomed to DocC documentation, you could also use this library to create your API documentation.
This would allow your developers to work in a familiar UI and effectively browse information in the environment they’re already used to.
If you don’t want to spend too much time configuring a layout from scratch, you could explore API documentation tools.
A good option is Swagger, a suite of API developer tools supported by SmartBear.
In addition to building API documentation, Swagger also maintains multiple documentation versions so that developers can quickly discover all available versions of your API and the accompanying documentation.
And if you decide to use the Archbee product documentation system, you’ll be able to integrate the Swagger API documentation into your knowledge base, making it easily accessible to all team members.
Include the Fundamental Sections
Similarly to selecting a standard API documentation layout, all your API docs should contain fundamental sections your development team can rely on to get the full picture of the API.
The findings of Postman’s 2021 State of the API Report have shown that only three percent of responders found the APIs they worked with satisfactory.
When asked for suggestions for improvement, respondents listed the elements they’d like to see more of.
The leading elements were better examples and sample code. Documentation standardization was also among the top responses.
So, knowing that developers want to see better examples and sample code, you should ensure you include those components in the documentation wherever applicable.
Let’s look at an excellent example of Stripe’s API documentation that has all elements a developer needs.
The documentation starts with a concise API description. There’s also a code example that changes depending on the library you select.
The description of the parameters is also a great addition to the document.
It’s worth noting that the sections to include will vary from API to API. However, we’ve compiled a list of elements you’ll find in most pieces of documentation:
- Resource description
- Resource URL
- Code examples
- Endpoints and methods
- Parameters
- Request examples
- Response example
- Status and error codes
Here's a read recommendation: How to Write API Documentation: The Ultimate Guide
Of course, it’s not always possible to include all of these elements. Still, having a consistent approach to writing API documentation is one of the best practices you can implement.
A predictable structure will bring uniformity to your documentation, making the use of APIs easier.
Enrich Your Documentation With Resources
Since a picture is worth a thousand words, one of the best practices you can enforce when building your API documentation is enriching it with resources such as screenshots or code samples.
API descriptions and error messages may be the crucial elements in the API documentation, but supplementing them with other resources is always worth it, even more so if the API contains UI elements.
And because we talked about API elements, here's 8 elements no API document should be without.
Let’s take a look at another portion of GitHub’s REST API documentation, the part about using an authentication app.
Even a cursory glance at the API documentation shows what the app looks like and which elements it has.
Rather than reading multiple sentences about the app, developers can simply refer to the screenshot.
Note, however, that you can also incorporate additional resources that go beyond visual elements.
An excerpt from PayPal’s REST API documentation provides a good example of that.
The section about tracking starts with the definition of the API and its functions. Readers are then immediately provided with code samples for each of the endpoints mentioned.
Since the primary purpose of API documentation is to shorten the amount of time needed to implement features using the API, your devs will be grateful for all steps you take to streamline the process.
A great method for making the API documentation more usable is by making it interactive.
For instance, you could fill the documentation with test data so that the devs can instantly run requests and examine the responses returned.
Deezer’s API documentation is an excellent example of an interactive approach to API.
The sandbox environment lets you test the endpoints and immediately get responses.
All in all, the screenshots, demo projects, and code samples you include in the documentation will facilitate the process of understanding the API.
The more effort API writers put into creating the documentation rich with resources, the sooner the devs can implement the features.
Maintain Your API Documentation
The crucial step you have to take to make the API documentation effective is to keep maintaining it.
This will prolong its usability and save your developers from struggling with outdated information.
Like all other pieces of software, APIs and API documentation are prone to change.
Documentation that lacks maintenance and updates is often a source of frustration, even more than no documentation at all.
However, changes to API are inevitable if you’re:
- Dealing with bugs
- Experiencing security issues
- Adding new features
- Removing features
- Rewriting code to improve it
‍
So, what’s the best practice for maintaining the documentation?
First of all, there’s no need to rewrite everything. Even if you’ve removed an endpoint, you should still keep the documentation visible for future reference.
In such cases, you should always flag deprecations. A deprecated API is one that is no longer recommended for use.
Such elements may be entirely removed or significantly rewritten, so you should warn the readers not to use them.
Here’s an example of one such warning from GitHub.
Since you’re dealing with internal API documentation, you could supplement deprecation warnings with a Slack notification to developers as an additional safety measure.
When it comes to adding new features, maintaining the API documentation is as simple.
A good practice is to create new documentation as soon as you introduce a new feature. This will ensure that your devs always have up-to-date information to work with.
You can also version the rest of your documentation to reference the new features.
Companies that fail at maintaining API documentation can expect loads of messages asking for clarification, so it’s best to take a proactive approach to maintenance and note changes as soon as they occur.
Conclusion
We’re not saying that creating API documentation is a cakewalk. The process requires planning, polishing, and maintaining.
Still, the effects of well-written internal API documentation are invaluable. Clear documentation improves the experience of those in your development team using the API.
So, the next time you revisit your internal API docs keep in mind these API documentation best practices you can follow and make sure they are all up to the industry standards and filled with useful resources.
‍
