Web API 接口设计规范

协议

API 与客户端通讯协议主要包含 http 和 https，建议使用https 确保交互数据的传输安全。

域名

主要包含两种形式：
主域名：https://api.example.com
子目录：https://example.org/api/

版本控制

版本控制主要用于 App、微信小程序、软件客户端等与系统不可同时实时更新的情况，来满足需要兼容旧版本的场景。
采用多版本并存，增量发布的方式。
版本号：v{n} n代表版本号，分为整形和浮点型
整型：大功能版本发布形式；具有当前版本状态下的所有API接口，例如：v1,v2
浮点型：为小版本号，只具备补充 api 的功能，其他 api 都默认调用对应大版本号的 api 例如：v1.1 v2.2

将版本号放入 URL 中：
https://api.example.com/v{n}/
这种方法比较方便和直观，版本号主要以整型为主。

将版本号放在请求头（Request Headers）中

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

版本号可使用整型、浮点型等

路径规则

路径又称 “终点”（endpoint），表示 API 的具体网址。
在 RESTful 架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的 “集合”（collection），所以 API 中的名词也应该使用复数。

举例来说，有一个 API 提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。
https://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees

请求方式

对于资源的具体操作类型，由 HTTP 动词表示。
常用的 HTTP 动词有下面四个（括号里是对应的 SQL 命令）。

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

例如：

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

传入参数

传入参数分为 3 中类型

地址栏参数

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

get方式的查询字串，此种方式主要用于过滤查询，如下：

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

请求 body 数据
主要用于提交新建数据等
请求头
用于存放请求格式信息、版本号、token 密钥、语言等信息。

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

返回格式

默认返回格式：

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

使用 json 格式作为响应格式，状态码分为两种：

statusCode: 系统状态码，用于处理响应状态，与 http 状态码保持一致，如：200 表示请求成功，500 表示服务器错误。
code：业务状态码，用于处理业务状态，一般 0 标识正常，可根据需求自行设计错误码对照表，参考微信官方文档，如下
https://developers.weixin.qq.com/doc/offiaccount/Getting_Started/Global_Return_Code.html
message 提示信息要进行统一，根据不同情况
data可以是JSON对象也可以是JSON数组，具体看业务需求。但要保证在不同情况下data的类型是一致的。
正常的后端接口响应，HTTP Status Code 默认返回 200，只有在下列情况时接口才会出现非 200 的情况：
当服务端鉴权失败时返回 HTTP Status Code 401
中间环节三方软件返回的标准错误码，例如 Nginx 返回的 5** 错误码
当接口 HTTP Status Code 非 200 时，返回的结构如下：

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

数组格式如下

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

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

分页列表格式

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