12 points to note when sharing interface design documents

Preface

We do back-end development, and we often need to define interface documents.

When I was doing interface document review recently, I found that the parameter defined by a small partner was an enumeration value, but the interface document did not provide the corresponding Specific enumeration value . In fact, how to write interface documents well is really important. Today, Brother Tianluo brings you 12 points to note in interface design documents~

• Public account: Little boy picking up snails (There is a carefully original interview PDF of snails)
• github address, thank you for every star: github

1. Are your interface names clear?

In other words, what does your interface do and is it easy to understand and clear? The general interfaceurl also requires that the function of the interface can be seen. For example, Query User Information (queryUserInfo) is a good interface name.

2. Is your interface address complete?

The address of the interface is also called the URL address of the interface. That is, what URL is used when others call your interface. For example, /api/user/queryUserInfo is an interface address. However, what I want to say is that this is not a complete interface address. Is your interface called HTTP?

If HTTP is called, what is the domain name? Port. A good http interface address should be like this:

https//tianluo.com:15000/api/user/queryUserInfo

3. Is your interface request method correct?

Interface request methods usually include the following:

• GET: To obtain resources from the server, you can pass parameters in URL, which is usually used to query data.
• POST: Submit data to the server, usually used for operations such as adding, modifying, and deleting.
• PUT: Update resources to the server, usually used to update data.
• DELETE: Delete resources from the server, usually used to delete data.
• PATCH: Partially updates resources to the server, usually used to modify some data.
• HEAD: Similar to the GET request, but only returns the response header and not the entity content. It is usually used to obtain meta-information of resources.
• OPTIONS: Request the server to return supported request methods and other information, usually used for the client and server to negotiate the request method.

When you define the interface document, you need to write clearly, which is your interface request method? Under normal circumstances, we use POST and GET more often. There are also companies that use POST for all interfaces.

4. 8 major elements of request parameters

When we define the interface, the request parameters are one of the most important parts . For a qualified interface document, the request parameters should contain these eight elements:

• Parameter name: The name of the parameter is named in camel case, such as userId.
• Type: The type of parameter, such as String, Integer, etc.
• Required: Whether the request parameters are required. If required, when the upstream does not pass this parameter, a parameter verification exception should be thrown.
• Default value: If this parameter is not passed, is there a default value and what is the default value.
• Value range: If it is a numerical type such as Long, Integer, this is a range value, such as 1~10, if it is an enumeration value, That is the enumeration range, such as ACTIVE, INACTIVE.
• Parameter format: For example, if your parameter is a date, you need to specify the parameter format, such as yyyyMMdd
• Input parameter example value: Provide an example value of the response parameter, So that developers can better understand and use this parameter.
• Remarks: If there are special instructions for this input parameter field, you can explain it in this column. If there is no special explanation, it is okay to just describe the function of this parameter.

The following is a sample document for entering parameters:

Parameter name	Type	Required or not	Default value	Value range	Parameter format	Input parameter example value	Remarks (description)
userId	Long	is	0L	0~99999999L	None	666L	UserId
birthDay	String	is	19900101	19900101~20231231	yyyyMMdd	19940107	User birthday

##5. 7 major requirements for response parameters

Response Parameters are actually similar to input parameters. There are 7 elements:

Parameter name: describes the name of the response parameter.
• Parameter type: describes the data type of the response parameter, such as
• String, Integer, etc.
Parameter format: describes the data format of the response parameter, such as
• yyyy-MM-dd, HH:mm:ss, etc.
Parameter description: Detailed description of the meaning of the response parameters.
• Value range: Describes the value range of the response parameter, such as
• integer range, string length, etc.
Required: Describes whether the response parameter is required.
• Example value: Provide an example value for this response parameter so that developers can better understand and use this parameter.

The difference is that the response parameters are generally returned in the format of

code, msg, data:

{
    "code": 0,
    "message": "success",
    "data": {
        "name": "Tom",
        "age": 20,
        "gender": "男"
    }
}

6. Interface error code

A good interface document must include error code enumeration. The general error code definition includes three columns:

Error code, error code information, meaning

##Error code##1001Parameter errorIllegal request parameter1002The user does not existThe corresponding user information was not found based on the given user ID Database error

Error information

Meaning

##1003

Database access error

7.接口安全

定义接口文档时，对于一些需要保护的接口，也需要考虑接口的安全，例如权限管理、防止 SQL 注入等。

因此，接口文档应当包含接口的安全性说明：例如接口的访问授权方式、数据传输加密方式等。此外，接口文档还应该对于敏感数据和操作进行标注，方便使用者注意隐私和安全问题。

8. 接口版本管理

在接口文档定义时，接口版本管理是非常重要的一个方面。由于软件项目的迭代和升级，接口可能会随着版本的变化而发生变化。为了避免接口变化给用户带来不必要的困扰，需要对接口进行版本管理。

以下是一些常用的接口版本管理方法：

• 在接口文档中明确版本号：在接口文档中明确标识接口的版本号，例如在接口地址中添加版本号信息，如https://example.com/api/v1/user，表示该接口的版本号为v1。
• 使用语义化版本号：采用语义化版本号（Semantic Versioning）规范，即版本号格式为X.Y.Z，其中X表示主版本号、Y表示次版本号、Z表示修订号。当进行兼容性变更时，需升级主版本号；当增加功能且不影响现有功能时，需升级次版本号；当进行bug修复或小功能改进时，需升级修订号。
• 增量发布：在接口发生变化时，先发布新版本的接口，同时保留旧版本的接口。用户可以根据自己的需求来选择使用哪个版本的接口。随着新版本的接口逐步替换旧版本的接口，最终可以将旧版本的接口废弃。

无论采用何种方法，接口版本管理都应该得到充分的考虑。在接口版本变化时，需要及时更新接口文档（详细描述版本的变化、兼容性问题、版本切换方式等），以确保用户能够获得最新的接口信息。

9. 维护接口文档更新迭代

如果接口发生了变更，比如参数有哪些变更，错误码变更等等，都需要维护到文档上。同时需要登记变更的记录。

日期	变更描述	操作人
2023-04-16	创建接口文档，定义了第一版接口文档	捡田螺的小男孩
2023-04-18	修改接口文档，增加了错误码，出参等	田螺哥

10.明确请求头有哪些

接口文档，是需要写清楚的请求头的。接口文档的请求头可以看到以下的信息：

• Content-Type：指定请求体的数据格式，如application/json、application/x-www-form-urlencoded、multipart/form-data等。
• Authorization：用于身份验证的令牌信息，如Token、Bearer等。
• Accept：指定客户端可以接受的响应数据格式，如application/json、text/html等。
• User-Agent：指定客户端的类型和版本信息，可以用于服务端进行针对性优化。
• Accept-Encoding：指定客户端可以接受的数据压缩格式，如gzip、deflate等。
• Cache-Control：指定客户端缓存的策略，如no-cache、max-age等。
• Cookie：包含客户端发送给服务器的cookie信息。

这是是一个接口文档的请求头的示例：

POST /api/user HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Accept: application/json
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36
Accept-Encoding: gzip, deflate, br
Cache-Control: no-cache
Cookie: _ga=GA1.2.1234567890.1234567890; _gid=GA1.2.0987654321.0987654321
If-None-Match: W/"2a-3TjT7VaqgkT1nJdKjX9Cpijp2FA"
Referer: https://example.com/login
Origin: https://example.com
Content-Length: 43

{"name": "John Doe", "age": 25, "email": "john.doe@example.com"}

11 接口请求示例

接口文档，需要提供接口的使用案例：以方便开发者理解接口的使用方法和调用流程。

12. 接口测试

一般来说，接口文档需要完善：接口测试的方法和测试结果，以便用户可以测试接口是否符合自己的需求，让用户用得放心~哈哈

The above is the detailed content of 12 points to note when sharing interface design documents. For more information, please follow other related articles on the PHP Chinese website!