# API 交互规范

对于数据请求的 API 数据接口,将使用 RESTful API 风格作为团队间数据交互的规范

# 协议

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

# 版本

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

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

# 接口路径

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

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

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

# HTTP 动作

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

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

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

实际应用场景示例

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

# 数据返回

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

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

GET /system/user 返回数据表格

{
  code: 0,
  msg: 'ok',
  data: {
    grid: {
      totalRow: 10,
      list: [...]
    }
  }
}
1
2
3
4
5
6
7
8
9
10

GET /system/user/:id 返回相关数据模型

{
  code: 0,
  msg: 'ok',
  data: { object }
}
1
2
3
4
5

POST /system/user 新增数据

{
  code: 0,
  msg: 'ok',
  data: { object }
}
1
2
3
4
5

新增业务数据的场景下,应将保存成功的数据进行返回,以满足部分业务需要在数据保存成功后提取相应数据字段进行后续操作,例如数据表单的数据,需要依次保存在 A 和 B 两个业务模块中,需要在 A 模块保存完成后,获得 A.id 并提供给 B 模块作为 B.aId 进行保存

PUT /system/user 更新数据

{
  code: 0,
  msg: 'ok',
  data: { object }
}
1
2
3
4
5

更新业务数据的场景,同样返回该操作保存成功后的完整数据内容,应用场景类似于上述的新增业务场景

DELETE /system/user/:id 删除数据

{
  code: 0,
  msg: 'ok',
  data: {}
}
1
2
3
4
5

删除成功,数据内容返回空即可;失败则使用常规错误模式输出相关信息

最后更新时间: 10/15/2020, 7:03:30 AM