协议

HTTPS 协议

接口版本

在header头中添加 “Api-Version” 描述接口版本

路由命名规范

动作 前缀 示例
获取 get get{XXX}
获取列表 get get{XXX}List
获取详情 get get{XXX}Detail
新增 add add{XXX}
修改 update update{XXX}
保存 save save{XXX}
删除 delete delete{XXX}
上传 upload upload{XXX}
发送 send send{XXX}

请求方式

请求方式 描述
GET 从服务器取出资源
POST 在服务器新建一个资源
PUT 在服务器更新资源
DELETE 从服务器删除资源

请求参数

请求头，存放公共参数、requestId、token、加密字段等。

Body

Body 体，存放请求接口的参数数据。

公共参数

WEB 端请求

参数 说明 备注
token 授权token 字符串
安全规范

敏感参数加密处理

登录密码、支付密码，需加密后传输，建议使用 非对称加密。

其他规范
  • 参数命名规范 建议使用驼峰命名，首字母小写。
  • requestId 建议携带唯一标示追踪问题。

返回参数

参数 类型 说明 备注
code Number 结果码 成功=1 失败=0
message String 显示信息 系统繁忙，稍后重试
error String 错误信息 便于研发定位问题
data Object 数据 JSON 格式

若有分页数据返回的，格式如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
{
	"code": 1,
	"message": "ok",
	"error": "",
	"data": {
		"list": [],
		"pagination": {
			"total": 100,
			"currentPage": 1,
			"totalPages": 10
		}
	}
}
安全规范

敏感数据脱敏处理

用户手机号、用户邮箱、身份证号、支付账号、邮寄地址等要进行脱敏，部分数据加 * 号处理。

其他规范
  • 属性名命名时，建议使用驼峰命名，首字母小写。
  • 属性值为空时，严格按类型返回默认值。
  • 金额类型/时间日期类型的属性值，如果仅用来显示，建议后端返回可以显示的字符串。
  • 业务逻辑的状态码和对应的文案，建议后端两者都返回。
  • 调用方不需要的属性，不要返回。