The tech-writer’s journal #16—Demystifying API Documentation: Best Practices for Technical Writers
More often than not, your documentation acts as the face of your product, and is a crucial part of any successful product. In this article, let us discuss API documentation and a few related best practices.
What is an Application Programming Interface (API)?
An API is a way for software to communicate with one another. The most commonly used analogy to explain an API is that of a restaurant. You go to a restaurant and order food. This involves the following:
- The customer or the user (API consumer)
- The menu or the front-end
- The waiter or the API
- The kitchen or the back-end
- Food or the data to be retrieved
When you order food, the waiter patiently takes your request with all the special requests, conveys the request to the kitchen and then delivers the food at your table. This is how APIs work in the world of software. The APIs carry your request to the server or the back-end with all the parameters, and in turn, retrieve and deliver the required data.
In a nutshell, APIs help software communicate with one another. APIs are basically used everywhere, and we currently live in the world of API economy. API economy refers to the usage of APIs to improve and optimize business processes. There are different types of APIs, some of them are:
- Internal APIs: APIs used inside a company to improve and optimize their internal processes
- External APIs : APIs that are built and provided by a third-party service that allows developers to integrate their applications with external systems.
APIs have been a huge contributor to many companies’ success such as Uber, Stripe, Twilio, and so on. Making APIs a paid-service has also become a successful business model. According to Postman’s 2023 State of the API report, nearly two-thirds of respondents are generating revenue from their APIs. Of those, 43% generate over a quarter of their company’s revenue through APIs. This has made many companies to become API-first companies. The primary USP here is that APIs allow you to use existing technology to grow your product instead of building everything from scratch.
Now that we have understood the importance of APIs and why we need to build them, let’s dive deep into API documentation.
API Documentation
An API reference document primarily explains to a user how to use the API.
Every API has two primary aspects:
- The API code
- The API documentation
As mentioned earlier, your documentation acts as the face of your product, and is a crucial part of any successful product. Without the API documentation, the developers wouldn’t know the purpose of your APIs and how to use them in their product. Your API document acts as a primary source of truth for your developers.
Creating clear and concise API documentation has a major impact on the overall developer experience, which is as important as user experience in any B2C or B2B product.
Most APIs today are designed using an Open API specification. The open API specification is a standard format that allows developers to describe the API in the format that is understandable by both developers and computers, which is YAML. The following is a sample of Open API specification:
openapi: 3.0.0
info:
title: customer
version: '1.0'
servers:
- url: 'https://api.example.com'
paths:
'/customers/{customer_id}':
parameters:
- schema:
type: integer
name: customer_id
in: path
required: true
get:
summary: customer
tags: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
customer_id:
type: integer
customer_name:
type: string
operationId: get-customers-customer_id
description: Retrieve a specific customer by ID
components:
schemas: {}Different parts of an Open API specification are:
- Open API specification version
- Name and description of the API
- Server locations
- Individual endpoints of an API
- Response codes and their descriptions
In a nutshell, the Open API specifications allows any developer to understand how to use an API. You can also choose to create API docs using automation tools like Postman and Swagger. However, this is bare minimum.
Given the success of the API economy and the number of companies and developers creating and consuming the APIs, you can invest some additional time, money and effort into creating custom API documentation.
Best Practices
Tips to improve overall developer experience
Understand your target audience
The key to writing successful documentation relies on two factors:
1. How well you understand your product: It is extremely important to have a solid understanding of your product before you even start documenting your first draft. You cannot document it if you don’t understand it in the first place.
2. How well you understand your target audience: Another pillar to creating successful documentation, is understanding your target audience. Having a good understanding of your audience and what they need helps you weed out all the unwanted and unrelated information, making the document clear, concise and to-the-point.
For example, consider Google Pay’s API documentation. The Google Pay’s API documentation is beginner-friendly and is written in plain language throughout. The key reason being, the person consuming the API documentation can be either a developer trying to integrate Google Pay into their product or a stakeholder who is trying to decide if the API offering is the right fit for their company or a journalist who is trying to analyze the best API offering in the market. Always ensure that your API documentation is in plain language, has links to useful resources and visual aids.
Ensure that your API documentation follows the user journey
A user journey covers all the interactions that the user has with your product, illustrating the natural thought and progression of the user. Ensure that you cover everything your user might need from exploring to implementing your API.
- The purpose of your API
- How do they access the API
- Specific API endpoints, requests, success response, and error responses.
Ensure that your API documentation follows the common format
Almost all the custom API documents out there use the same format so that it is intuitive to use. Most API docs use a two or three column layout — the menu on the right, the document in the center pane and the code in the right pane.
Keep your API documentation up to-date
As mentioned earlier, your product is only as good as your document. Ensure that your API documentation has a proper maintenance strategy. Ensure that you do the following for your data:
- Update documentation for every product update
- Periodically remove deprecated data
- Analyze user pain points and create more effective documentation for the same.
A Few API References
Some of the successful API documentation sites that you can refer to:
