12 points to note when sharing interface design documents

Preface

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

When I was doinginterface document reviewrecently, I found that theparameter defined by a small partner was an enumeration value, but the interface document did not provide thecorresponding Specific enumeration value. In fact, how to write interface documents well is really important. Today, Brother Tianluo brings you12points 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 interfaceurlalso requires that the function of the interface can be seen. For example,Query User Information (queryUserInfo)is agood interface name.

2. Is your interface address complete?

The address of the interface is also called theURLaddress of the interface. That is, whatURLis used when others call your interface. For example,/api/user/queryUserInfois aninterface address. However, what I want to say is that this is not a complete interface address. Is your interface calledHTTP?

IfHTTPis called, what is thedomain name?Port. A goodhttpinterface 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 inURL, 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 theGETrequest, 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 usePOST and GETmore often. There are also companies that usePOSTfor all interfaces.

4. 8 major elements of request parameters

When we define the interface, the request parameters areone 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 asuserId.
• Type: The type of parameter, such asString, 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 asLong, Integer, this is a range value, such as1~10, if it is an enumeration value, That is the enumeration range, such asACTIVE, INACTIVE.
• Parameter format: For example, if your parameter is a date, you need to specify the parameter format, such asyyyyMMdd
• 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 arespecial instructionsfor 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"}