When everything works, documentation is easy to ignore. But after a severe breakdown, the need for API documentation surfaces. With the growth of APIs, we see an increase in demand for technical writers who know how to write API documentation.
Writing API documentation is a collaborative process since the technical writer needs to collaborate with the development team. The reality is that in some organizations, anyone can wear the hat and write API docs, at least for a while.
I wrote this guide for those who need to kickstart learning about API concepts and writing docs.
So, what is an API?
In simple terms, API is an acronym for an application programming interface. It allows two applications to communicate with one another to access data. The essence of APIs is requests and responses. When you take action on your phone, like checking the weather, a request is sent to an API to access and deliver that information.
APIs are an evolution in the computing industry. If you want a quick intro in this world, check the Martin Casado video from a16z explaining the context of APIs and how companies are leveraging them.
What is API documentation?
API documentation contains information about the API functionality, endpoints, parameters, requests, and responses with explicit descriptions so developers can implement the APIs.
The application programming interface is becoming for more and more companies interface for business. The API economy has been booming with a high growth rate in the past years, so API documentation is vital for any business with public or internal APIs.
The best way to understand API documentation is to look up some examples. One of the best out there is Stripe API Reference.
Let's take a look at this one - Creating a Price from Stripe docs.
I've highlighted the sections in the API docs. It starts with a description of what the endpoint does. On the right side, you can see code examples and the response body. The code examples may be different depending on the library the developer is using. A critical section is the one where an API writer describes the parameters.
- Resource description
- Resource URL
- Code examples
- Endpoints and methods
- Request examples
- Response example
- Status and error codes
Since API docs typically follow similar structures, you can quickly create templates for them. The idea is to find a design that helps you and repurpose it.
What are the types of API Documentation?
Understanding the types of API docs helps structure the content. You will find various categorizations, but most of the time, we split API documentation into three:
This is the backbone of the API documentation because it provides information about the structure, parameters, and return values for each function or method in an API.
The developers use this piece the most, so it gets the most attention. Thus, it needs to be spot on. More precisely, describe all the things. I cannot emphasize enough: all the endpoints and assets, resources, units, forms, as well as response codes and errors. Every single thing.
Check out SendGrid. As you can see, you have the API reference, and the Get Started path. Usually, the conceptual documents describe how it works, the resources, and how they interconnect. It describes the kinds of things you can do and summarize some common patterns.
Rather than just describing every function individually, conceptual documentation describes how APIs can be used to build applications. It also explains integrating multiple APIs into a single application (e.g., functions that work together).
These will typically include a tutorial or information about the API keys needed to authorize requests.
Tutorials provide step-by-step guides for how to do specific stuff with the APIs. There are usually detailed instructions on the use of each function call and parameter. When you want to point your users to particular use cases, tutorials are key to your documentation.
If you're structuring your API documentation, you should keep these three types in mind. You might only need to write references, but know that good API docs are more comprehensive.
What should be included in API documentation?
Before you answer this question, you need to know who your users are. You can write documentation for developers or technical marketers. These two will probably never overlap. Therefore what you will include in your documentation will differ.
Also, knowing your audience will help you determine which programming languages are popular among your audience so you can provide relevant code snippets and what type of tutorials you need to publish.
Probably you have noticed that API documentation varies significantly between companies.
To set yourself up for success, no matter the structure you choose, try to solve and include these four points in your API documentation:
- What does a user need to submit to an endpoint to get back the exact data or perform a specific action
- What is the authentication requirements for accessing the resources
- What information is returned, and how should it be interpreted
- Try it out section
Who writes API documentation?
You don't need to be a programmer to write API documentation. Still, you do need a technical background. Writers will be collaborating with developers, and it does help to have some skills.
For example, people with solid tech knowledge can do authoring, publishing, and editing. If you are tech weak, then maybe just publishing, and somewhere in between, you can edit and publish.
Whoever writes the API docs needs to understand how an API works to describe them.
Depending on the organization, you will have various people handling the documentation, but usually, they are:
Who better knows the code than the people who wrote it? So developers are an obvious choice.
There’s a debate around whether they are suitable for writing docs, and, indeed, this is rarely a good idea because developers are famous for being bad technical writers.
Also, documentation is not a priority for a developer, but it doesn’t mean that they shouldn’t write at all.
Developers need to document enough of their code so that writers get the idea and add information that is not obvious. Having notes is not complex, and it can come in the form of code documentation or notes.
Technical API writers
This is the group that will most likely handle the API documentation. Usually, writers don’t have programming experience (except if they transitioned from a developer role to a technical one), so they work closely with the devs. As a technical writer, you can learn along the way, and the key is to understand the concepts, not necessarily have the skills to write code from scratch.
Whoever wears the hat
As the name suggests, this is a role that is not defined in the organization, and somebody still needs to do it. Sometimes you will find product owners, startup founders, content writers, and everything in between. The essential skill here is to be good at writing and have technical knowledge.
Usually, they can speak the jargon, read and write code or examples, and most importantly, sympathize with the users.
No matter who wears the API writer’s hat, the role needs to bring clarity, structure, and explanation to the documentation. Also, the person that writes API docs needs to know what they are responsible for. Are you writing it from scratch or just editing. Who will be writing the code examples, and how are you going to handle versioning.
Ideally, you will have a review process to keep those typos out of the public eye when publishing API documentation.
How do I create an API document?
There are different types of APIs, but 82% of organizations use the OpenAPI Specification (formerly known as Swagger) in their API development, so we will start an API document with SwaggerUI.
Swagger UI custom block
From the Archbee editor, add the SwaggerUI block.
The block will emulate what the API would look like for a Petstore, that’s why the default URL is Petstore, and you need to add your own URL.
You can point-and-click through various fields to explore different requests and the parameters available. These features let you generate an API call and see the result.
API Endpoint custom block
Many companies are not providing standardized APIs (like OpenAPI specifications), so the API endpoint block lets you describe your API.
Usually, you will receive from the development team details about the API. Engineering departments might use Postman to organize their work.
When working together with outside teams or communicating an API specification internally, instead of providing a JSON file, you create an API document and describe anything from URL, Parameters, Request structure, Response structure.
Here’s a quick video demonstration of how you can leverage these blocks.
API Documentation Tools
There are many tools for API documentation, from open source to commercially available.
Suppose a developer needs to document the API. In that case, it will usually treat documentation as the software - using git, markdown, and building it from the code - usually, docs as code model.
On the other hand, if you wear the API writer hat, you will probably need a tool with an intuitive editor. Here are some common API doc tools:
- Github pages
- Headless CMS's
- Static site generators
Best practices and resources for API documentation
There are no universally accepted best practices. The feedback from your users is essential, but to start on the right track, here are some ideas:
- Spend time to write a solid introduction providing a starting point
- Describe the resources. What does the endpoint do?
- If possible, create a single-page API document
- Describe every parameter
- Describe the request body
- Describe the response body
- Describe the headers, API authentication methods, and error codes
- Avoid jargon - terms that you are using internally might not make sense for others
- Double-check and publish
- Always maintain the API docs
If you want to become an API writer, there are great resources around the web:
- Best practices by Write the Docs community
- Google documentation guide
- If you want to build your portfolio, try Season of Docs
- Tips on how to write and maintain simple, intuitive
API documentation is unique in several ways, but the most critical aspect is that it sells the product. It is crucial to pick the right tool and to know who owns the API documentation.
If your documentation lacks information or does not offer a try-out, you might be missing out because product docs are a growth loop, and they can be your biggest marketing tool.