How to Design a Standard API Interface Documentation

What is API Interface Documentation?

API Interface (Application Programming Interface) refers to the data communication and exchange between systems through artificially preset rules and protocols.

If the Internet is compared to a commercial street, then various application programs on the Internet are like shops on this street. They provide entrance and service guides for customers, and the goods in the shops are the services they can provide. These goods that can meet user needs are various API functional interfaces. Ordinary users only need to obtain the desired goods through simple page interactions; for developers, a simple command line can obtain the most critical information.

Users do not need to understand the complex development and design process behind the entire store, nor do they need to learn about the logical implementation behind a certain product, but choose the product that can directly meet their needs, and read the product's usage instructions to easily obtain specific data in the store. From providing an Instagram login and registration function for a blog to integrating financial payment and settlement pages for an e-commerce website, all of these cannot do without various API interfaces.

The essence of an API interface is a predefined function logic. How to understand it? For example, to integrate a bank card payment settlement entrance for an e-commerce website, after the customer completes the payment, the website automatically increases the wallet balance for the corresponding account. The link between payment and balance increase is a logical function. Third-party applications also increase additional API interfaces, which make themselves more extensible and customizable. They also reduce development costs and improve user experience. Additionally, they provide more service choices for users.

To use various interface functions properly, it is necessary to clearly understand what format of request should be input to obtain the expected result, and then understand the calling logic of the interface. Each interface has its own usage method, so each interface requires a user manual, which is also called API interface documentation.

How to Design a Clear API Interface Documentation?

After understanding what an API interface is and the role of interface documentation, we can move on to explore the core elements that should be present when designing API interface documentation. A clear and complete API interface document for the developer community should have the following key points:

• Clarify the interface address and request method.
• A detailed description of the interface details.
• Write interface examples.
• Design interface error codes.
• Introduce version control.

1. Clarify the Interface Address and Request Method

Before starting to write the API interface documentation, interface design is required to clarify the functions, application scenarios, and usage methods that each API interface can provide to ensure that the interfaces to be used are technically and operationally feasible. The interface address does not refer to a specific webpage but a place where users can find the service. Similar to a product name, users can quickly find it when they have a demand and enter the name.

After finding a specific interface address, how to use it? Common API request methods include: add (POST), modify (PUT), delete (DELETE), and obtain (GET).

2. Detailed Description of Interface Information

After defining the interface address, it is now necessary to provide users with more information about the interface, including the interface name, function description, request parameters, request examples, response parameters, response examples, etc. Among them, the request parameters and response parameters need to describe in detail the data type, whether it is a required item, and parameter explanation for each of the parameter. The amount of interface information determines the user's experience when using the API interface.

3. Writing Interface Examples

Interface examples are an important part of the documentation that helps developers understand and better debug how to use the API. The examples should be written in such a way that the API interface is correctly represented and the meaning and role of each parameter should be clearly explained, including examples of successful and failed calls.

4. Design Interface Error Codes

Error codes should be designed based on the characteristics and requirements of the API. The error code should clearly indicate the reason for the problem and provide solutions and suggestions to help developers diagnose and solve problems faster. Listing well-designed error codes in the API document can improve the usability and reliability of the interface and reduce the troubleshooting time of developers. The following are the types of API error codes available for reference:

• Client error: Client errors usually indicate that there is a problem with the request sent by the client, such as missing parameters, format errors, insufficient permissions, etc. Common client error codes include 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, etc.
• Server error: Server errors usually indicate that there is a problem with the API server, such as internal server errors, database connection errors, timeouts, etc. Common server error codes include 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, etc.
• Business error: Business errors usually indicate that the API cannot complete the client request because the request data does not comply with business rules or the API cannot process the request. Common business error codes include 422 Unprocessable Entity, 429 Too Many Requests, 451 Unavailable For Legal Reasons, etc.
• Authentication and security errors: Authentication and security errors usually indicate that the API needs to verify the client's identity, but cannot verify or authentication fails. Common authentication and security error codes include 401 Unauthorized, 403 Forbidden, 419 Authentication Timeout, 498 Invalid Token, etc.
• Limit and quota errors: Limit and quota errors usually indicate that the API has exceeded certain limits or quotas, such as exceeding the request rate limit or quota. Common limit and quota error codes include 429 Too Many Requests, 503 Service Unavailable, 509 Bandwidth Limit Exceeded, etc.

5. Introducing Version Control

As the functionality of the API continues to improve, modifications may be made to the interface, such as adding, deleting, or changing parameters, or changing the format of the return results. Without version control functionality in the API documentation, these new changes may affect the user's API experience, causing existing clients to become unusable. Introducing good version control functionality can mark the interface content in different versions, and developers can choose different versions according to their needs, thereby better understanding the differences and changes between different versions of the current API.

Create Easily API Interface Documentation with Apidog

Writing a qualified API interface documentation requires dual skills in technology and language, as well as attention to detail and standards. Only by writing a standardized, complete, and clear API interface documentation can the development efficiency and code quality of the project be improved. Apidog is an integrated API collaboration platform that can achieve API documentation, API debugging, API Mock, and API automation testing, and is a more advanced API design/development/testing tool. With Apidog, designing a standardized, complete, and clear API interface documentation is no longer difficult.