# API 交互规范

对于数据请求的 API 数据接口，将使用 RESTful API 风格作为团队间数据交互的执行规范，本文设定的范围仅为应用频次最多的业务场景，例如数据的 新增、修改、删除、详情 以及 数据表格/列表 等场景

内容目录

协议
版本
接口路径
HTTP 动作
数据响应结果

# 协议

对于生产环境与测试环境，应总是使用 https 协议，开发环境则视方便情况而定

# 版本

版本（Versioning）应在 URL 中作为预留接口版本号，以方便后续因大版本升级需要保留旧版本接口的情况下增加新版本接口的场景

https://api.maimaimai.com/v1/user/list

# 接口路径

路径又称"终点"（endpoint），表示 API 的具体网址。

# 名词应用复数

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

https://api.maimaimai.com/v1/mall/orders
https://api.maimaimai.com/v1/mall/products
https://api.maimaimai.com/v1/mall/users

# 业务关系结构描述

对于接口路径的设置，建议使用模块上下级关系进行联合描述，一来模块清晰，二来可读性佳；另外，对于使用的英文单词应使用 全小写 模式，有词组的情况使用 - 隔开，详细的规则可参考：路由命名规则

https://api.maimaimai.com/v1/system/users/role-auth

上例指定了 系统管理 -> 用户管理 -> 角色授权管理 的功能接口

# 避免多级 URL

很多时候，资源需要进行多级分类，很容易写出多级的 URL，比如获取编号为 37 的产品的编号为 5 的优惠券

GET /products/37/coupons/5

上述 URL 不利于扩展，语义不明确，往往无法在第一时间了解其含义

更好的做法是，除了第一级，其他级别都用查询字符串表达

GET /products/37?coupons=5

# HTTP 动作

对于 RESTful API 风格的应用，很重要的部分是使用 http 标准动词对操作类型进行描述，所以在定义 url 时不能有动词内容

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

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

弃用的动作

经过讨论，API 标准中不应用 PATCH 动作

实际应用场景示例

URL 示例	HTTP 动词类型	描述
/system/users/search	POST	获得用户列表（数据表格）
/system/users/:id	GET	获得单个用户明细数据
/system/users	POST	新增用户
/system/users/:id	PUT	修改用户
/system/users/:id	DELETE	删除用户

# 数据响应结果

根据不同的操作类型，返回的数据格式应符合以下规范

数据交互的基础模型以及数据表格数据结构请参考：数据交互格式标准

数据表格及查询

用于业务的数据表格（前端数据表格）以及数据列表（APP 的无限滚动列表）的接口，约定统一命名为 search

由于数据表格查询的过程中存在提交大量业务条件的场景（例如数据表格配套的查询表单中存在大量可设定的查询条件），本接口应用的请求动作统一设置为 POST

// request
POST /system/users/search

{
  name: 'zhangsan',
  pageNumber: 1,
  pageSize: 10
}

// response
{
  code: 0,
  msg: 'ok',
  data: {
    grid: {
      total: 53,
      list: [
        { object },
        { object },
        { object },
        { object },
        ...
      ]
    }
  }
}

查询数据详情

// request
GET /system/users/:id

// response
{
  code: 0,
  msg: 'ok',
  data: { object }
}

新增数据

// request
POST /system/users

// response
{
  code: 0,
  msg: 'ok',
  data: { object }
}

更改数据

// request
PUT /system/users/:id

// response
{
  code: 0,
  msg: 'ok',
  data: { object }
}

删除数据

// request
DELETE /system/users/:id

// response
{
  code: 0,
  msg: 'ok',
  data: { object }
}

提示

通过观察可发现，数据的 新增、修改、删除 以及 详情 均在请求成功后，返回操作目标对象的完整模型数据，用以满足部分业务需要在数据保存成功后提取相应数据字段进行后续操作

例如数据表单的数据，需要依次保存在 A 和 B 两个业务模块中，需要在 A 模块保存完成后，获得 A.id 并提供给 B 模块作为 B.aId 进行保存

← 数据交互格式标准登录模块 →