Web API interface design specifications

Web API interface design specifications

protocol

The API and client communication protocols mainly include http and https. It is recommended to use https to ensure the security of interactive data transmission.

domain name

Mainly includes two forms:
main domain name: https://api.example.com
Subdirectory: https://example.org/api/

version control

Version control is mainly used when apps, WeChat applets, software clients, etc. and the system cannot be updated in real time at the same time to meet scenarios where compatibility with older versions is required.
Adopt multiple versions to coexist and incremental release.
Version number : v{n} n represents the version number, which is divided into integer and floating-point
type . Integer type : large-function version release form; has all API interfaces in the current version status, for example: v1, v2.
Floating-point type : is a small version. number, only has the function of supplementing the API. Other APIs will call the API corresponding to the larger version number by default. For example: v1.1 v2.2

Put the version number into the URL:
https://api.example.com/v{n}/
This method is more convenient and intuitive. The version number is mainly integer.

Put the version number in the request header (Request Headers)

headers:{
    
    
    version: 'v{n}'
    ...
}

The version number can use integer, floating point, etc.

Path rules

The path is also called the "endpoint" and represents the specific URL of the API..
In RESTful architecture, each URL represents a resource , soThere cannot be verbs in the URL, only nouns, and the nouns used often correspond to the table names of the database.. Generally speaking, tables in a database are "collections" of records of the same type, so nouns in the API should also be pluralized.

For example, if there is an API that provides zoo information, including information about various animals and employees, its path should be designed as follows.
https://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees

Request method

Specific operation types for resources are represented by HTTP verbs.
There are four commonly used HTTP verbs (the corresponding SQL commands are in brackets).

GET（SELECT） //从服务器取出资源（一项或多项）。
POST（CREATE）//在服务器新建一个资源。
PUT（UPDATE） //在服务器更新资源（客户端提供改变后的完整资源）。
DELETE（DELETE）//从服务器删除资源。

For example:

GET /product   //列出所有商品
POST /product  //新建一个商品
GET /product/ID //获取某个指定商品的信息
PUT /product/ID //更新某个指定商品的信息
DELETE /product/ID //删除某个商品
GET /product/ID/purchase //列出某个指定商品的所有投资者
GET /product/ID/purchase/ID //获取某个指定商品的指定投资者信息

Pass in parameters

The incoming parameters are divided into 3 types:

1. Address bar parameters

restful 地址栏参数 /api/v1/product/122 
// 122 为产品编号，获取产品为 122 的信息

Query string in get mode. This method is mainly used for filtering queries , as follows:

?limit=10  //指定返回记录的数量
?offset=10 //指定返回记录的开始位置。
?page=2&per_page=100 //指定第几页，以及每页的记录数。
?sortby=name&order=asc //指定返回结果按照哪个属性排序，以及排序顺序。
?producy_type=1  //指定筛选条件

2. Requesting body data
   is mainly used to submit new data, etc.
3. The request header
   is used to store request format information, version number, token key, language and other information .

{
    
    
    Accept: 'application/json',     //json格式
    version: 'v1.0'                       //版本号
    Authorization: 'Bearer {access_token}',   //认证token
    language: 'zh'                      //语言
}

Return format

Default return format :

{
    
    
    errorCode: 0,                    //状态码
    message: 'ok',                   //提示信息
    data: {
    
    }                         //主体数据
}

Using json format as the response format, the status code is divided into two types:

• statusCode: system status code, used to process response status, consistent with http status code, such as: 200 means the request is successful, 500 means server error.
• code: Business status code, used to process business status. Generally, 0 indicates normal. You can design an error code comparison table according to your needs. Refer to the official WeChat documentation, as follows:
  https://developers.weixin.qq.com/doc/offiaccount/Getting_Started /Global_Return_Code.html
• message prompt information should be unified, according to different situations
• data can be a JSON object or a JSON array, depending on the business requirements. But make sure that the data type is consistent under different circumstances.
• Normal backend interface response, HTTP Status Code returns 200 by default. The interface will only appear non-200 in the following situations: when the
  server authentication fails, HTTP Status Code 401 is returned.
  The standard error code returned by the third-party software in the intermediate link. For example, the 5** error code returned by Nginx
• When the interface HTTP Status Code is not 200, the returned structure is as follows:

{
    
    
    "errorCode": {
    
    通用处理结果代码},
    "data": null,
    "message": "对应的错误消息"
}

• The array format is as follows

{
    
    
    "code": 0,
    "message": "SUCCESS",
    "data": [
            {
    
    
                "id":1,
                "name":"小王",
                "age":20
            },
            {
    
    
                "id": 2,
                "name": "小李",
                "age": 30
            }
        ]
}

{
    
    
    "code": 0,
    "message": "SUCCESS",
    "data": [
        "小李",
        "小王"
    ]
}

• Paginated list format

{
    
    
    "code": 0,
    "message": "SUCCESS",
    "data": {
    
    
        "pageSize": 10,
        "page": 12,
        "total": 118,
        "list": [
            {
    
    
                "id": 1,
                "name": "小王",
                "age": 10
            },
            {
    
    
                "id": 1,
                "name": "小王",
                "age": 10
            }
        ]
    }
}