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: 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.

code, msg, data:

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

Error code, error code information, meaning

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"}