Are You Developing Productive API Documentation?
Documenting the technical process of an application has always been a vital part of the development lifecycle. It not only explains how to implement a certain feature but also serves as a future-proof information log.
Most modern applications are decoupled and often developed independently. The tech stacks on the backend and the frontend can be completely different and still communicate effectively, all thanks to APIs.
An application programming interface (API) is essentially an interface exposing several methods/operations that can be invoked outside of where it is defined---it is basically an abstract implementation. There are various types of APIs, but the most popular ones are the REST API and GraphQL.
While most people see writing effective APIs as important, I feel documenting them is equally important.
Why Document APIs?
The foremost question that arises is: If developers are aware of the RPCs, methods, and operations, why document them?
Well, first, not all APIs are meant for internal purposes. In many instances, APIs are developed to be used by developers outside the organization to help them build on top of it. Allowing developers to quickly and easily incorporate an API into their own applications with clear and detailed documentation will help both the API provider and developer save time and resources.
Furthermore, thorough documentation can aid in lowering the volume of help requests and inquiries, freeing the API provider to concentrate on other activities. Overall, thoroughly explained APIs can enhance user experience and make it simpler for developers to utilize the API.
How to Develop Productive API Documentation?
Now that we understand the value of creating API documentation, the next important thing to know is how to write productive API documentation. Obviously, we can't just throw a bunch of information at the user and leave them to figure things out on their own. While creating API documentation, one must structure the information productively. Here are some points to keep in mind while creating API documentation.
Firstly, start by giving a general overview of the API, including the purpose and its main concepts, and the features the developers need to know. Next, provide detailed information about the different endpoints that the API exposes, including the URLs, supported methods (such as GET, POST, etc.), and any input and output parameters.
Be sure to include examples of how to use the API, including sample requests and responses, to help developers understand how to integrate it into their own projects.
Consider providing a reference section that lists the details of all the available endpoints, along with their input and output parameters, in a clear and concise format.
Finally, make sure to provide contact information so that developers can reach out with any questions or feedback they have.
Best Practices for Productive API Documentation
As discussed in the above sections, one must start with an overview, which provides basic information about the API, its usage, and explaining all the endpoints with examples. You can also use the Backstage developer portal to enhance the API docs.
For those of you who are unfamiliar with the Backstage developer portal, it is an open-source platform for building developer portals. It is designed to make it easy for teams to document and manage their APIs and other software products. With Backstage, you can create a central location where developers can find all the information they need to use your APIs, including detailed documentation, reference materials, and examples.
With Backstage, you can easily create a comprehensive and user-friendly developer portal for your API, making it easier for developers to find the information they need and start using your API.
You should also update the documentation as and when the API evolves and changes over time. Also, make the documentation easy to access and navigate, so that developers can quickly find the information they need.
Example of Good vs Bad Documentation
To understand things better, let us see the difference between a well-documented and poorly documented API by taking an example of an API that allows developers to access the product catalog of a company and place orders.
First, let's look at the first example.
Overview
The XYZ API allows developers to access the company's product catalog and place orders.
Endpoints
GET /products: returns a list of products, with optional search and filtering parameters
POST /orders: creates a new order, with the specified products and quantities
GET /orders/{id}: returns the details of the specified order
Examples
Here are some examples of how to use the XYZ API:
- To retrieve a list of products, send a GET request to /products with the following parameters:
- q: the search query (optional)
- category: the product category to filter by (optional)
- To create a new order, send a POST request to /orders with the following JSON body:
{
"products": [
{"id": "123", "quantity": 2},
{"id": "456", "quantity": 1}
]
}
- To retrieve an existing order, send a GET request to /orders/{id}, where {id} is the order ID.
Reference
- GET /products: returns a list of products
- q: the search query (string, optional)
- category: the product category to filter by (string, optional)
- Response: a JSON array of product objects
- POST /orders: creates a new order
- Body: a JSON object with the following properties
- products: an array of product objects, each with an "id" and "quantity"
- Response: a JSON object with the following properties
- id: the order ID (string)
- total: the total cost of the order (number)
- GET /orders/{id}: returns the details of the specified order
- Path parameters:
- id: the order ID (string)
- Response: a JSON object with the following properties
- id: the order ID (string)
- products: an array of product objects, each with an "id", "name", "price", and "quantity"
- total: the total cost of the order (number)
Authentication
To use the XYZ API, you must first obtain an API key by signing up for an account at xyz.com/api. Then, include the API key in the "Authorization" header of each API request, like this:
Authorization: Bearer YOUR_API_KEY
Contact
If you have any questions or feedback about the XYZ API, please contact us at api@xyz.com.
Notice, how the structure of the API starts off with an overview, lists all the endpoints, and then goes on to explain the usage along with demonstrated examples. It even talks about the authentication required to use the API and then calls off by giving contact information for further queries or feedback.
Now see this other API.
Overview
The XYZ API allows you to do stuff with our products.
Endpoints
/products
/orders
/orders/{id}
Examples
Just use the endpoints like this:
/products?q=foo&category=bar
{"products": [{"id": "123", "quantity": 2}, {"id": "456", "quantity": 1}]}
/orders/{id}
Reference
- /products: returns a list of products
- q: search query
- category: filter by category
- Response: array of product objects
- /orders: creates a new order
- Body: object with "products" array
- Response: object
Although this example too, follows a structure, it is clearly failing to provide enough information to the developers and is lacking attention to detail. This documentation is also missing the response structure from the server on a query. Additionally, contact information is missing too, which impedes developers from contacting the API maintainers to get any queries resolved.
Conclusion
In general, the goal of API documentation is to provide clear and concise information that is easy for developers to understand and use. By following these steps, you can help ensure that your API documentation is clear, concise, and easy to use, which can improve the developer experience and make it easier for them to work with your API.