Interface problem
1. Agreement
The communication protocol between the API and client users always uses the HTTPS protocol to ensure the security of the transmission of interactive data.
2. Domain name
You should try to deploy the API under a dedicated domain name: https://api.example.com
If you are sure that the API is very simple and will not be further expanded, you can consider placing it under the main domain name: https://www.example.com/api
3. Version control
https://api.example.com/v{n}
1. The version number of the API should be put into the URL.
2. Adopt the coexistence of multiple versions and incremental release.
3. n represents the version number, which is divided into integer and floating point types.
Integer type: large function version, such as v1, v2, v3...
Floating point type: Supplementary function version, such as v1.1, v1.2, v2.1, v2.2...
4. For an API or service, a maximum of 3 most detailed versions should be retained in production
4. Path rules
The path is also called the "end point" and represents the specific URL of the API.
1. In the RESTful architecture, each URL represents a resource, so the URL cannot have verbs, only nouns.
[The nouns used often correspond to the table names of the database]
2. The tables in the database are generally "collections" of the same type of records, so the nouns in the API should also be pluralized.
Example: https://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees
5. Request method
GET (SELECT): Retrieve resources (one or more items) from the server.
POST (CREATE): Create a new resource on the server.
PUT (UPDATE): Update resources on the server (the client provides the complete changed resources).
DELETE (DELETE): Delete a resource from the server.
example:
GET /v1/products Get all products
GET /v1/products/ID Get information about a specified product
POST /v1/products Create a new product
PUT /v1/products/ID updates the information of a specified product
DELETE /v1/products/ID deletes a product. For a more reasonable design, see [9. Non-RESTful API requirements]
GET /v1/products/ID/purchases List all investors of a specified product
GET /v1/products/ID/purchases/ID Get the specified investor information for a specified product
6. Filter information
If there are a large number of records, it is impossible for the server to return all records to the user.
The API should provide paging parameters and other filtering parameters to filter the returned results.
/v1/products?page=1&pageSize=20 specifies the page and the number of records on each page.
/v1/products?sortBy=name&order=asc specifies which attribute the returned results are sorted by, and the sort order.
7. Pass in parameters
Incoming parameters are divided into 4 types:
1. Cookie: Generally used for OAuth authentication
2. Request header: Generally used for OAuth authentication
3. Request body data:
4. Address bar parameters:
1) restful address bar parameter /v1/products/ID ID is the product number, get the information whose product number is ID
2) For query fields in get mode, see [6. Filtering information]
8. Response parameters
response:
----------------------------------------
{
status: 200, // See [status] for details
data: {
code: 1, // See [code] for details
data: {} || [], // data
message: 'Success', // Store the response information prompt and display it to the client user [Semantic Chinese prompt required]
sysMsg: 'success' // Store response information prompts, used for debugging, both Chinese and English are acceptable
... // Other parameters, such as total [total number of records], etc.
},
message: 'Success', // Store the response information prompt and display it to the client user [Semantic Chinese prompt required]
}
----------------------------------------
【status】:
200: OK 400: Bad Request 500: Internal Server Error
1002: Runtime Exception
1003: Unauthorized
403: Forbidden
404：Not Found
【code】:
1: Data acquisition successful | Operation successful 0: Data acquisition failed | Operation failed
9. Requirements for non-RESTful APIs
1. In the actual business development process, there may be various APIs that cannot be implemented by simple RESTful specifications.
2. There needs to be some APIs that break through the restful normative principles.
3. Especially the API design of mobile Internet requires some specific APIs to optimize the interaction of data requests.
1). Delete single | batch delete: DELETE /v1/product body parameters {ids: []}
2) Page-level API: Return all the data needed in the current page through an interface at once
10. Consistency principle
1. What fields are required by the front end and what fields should be returned by the API interface? No more and no less fields.
2. The update function should try to ensure that the original data parameters returned for the first time have the same structure as the data parameters submitted for update.
3. Time parameters should be passed in strings with a consistent format as much as possible, such as:
‘2019-01’ | ‘2019/01’
‘2019-01-01’ | ‘2019/01/01’
‘2019-01-01 12:12:12’ | ‘2019/01/01 12:12:12’
4. Other parameters [to be updated]
11. Interface documentation
1. Use automated interface documents as much as possible to enable online testing and synchronous updates.
2. Should include: interface BASE address, interface version, interface module classification, etc.
3. Each interface should contain:
Interface address: Does not include the interface BASE address.
Request method: get, post, put, delete, etc.
Request parameters: data format [default JSON, optional form data], data type, whether required, Chinese description.
Response parameters: type, Chinese description.
12. Reference materials
- [https://my.oschina.net/qqlet/blog/1922038](https://links.jianshu.com/go?to=https%3A%2F%2Fmy.oschina.net%2Fqqlet%2Fblog %2F1922038)
- https://juejin.im/post/5afee0e86fb9a07ab379b371