API 接口 记录

路由命名规范

获取		get			get{XXX}
获取		get			get{XXX}List
新增		add			add{XXX}
修改		update		update{XXX}
保存		save		save{XXX}
删除		delete		delete{XXX}
上传		upload		upload{XXX}
发送		send		send{XXX}

请求方式

GET			获取数据
POST		新增数据
PUT			更新数据
DELETE		删除数据

标准的RESTful API示例如下：

POST /customers：创建一个消费者
GET /customers：获取消费者列表
GET /customers/{id}：获取某个具体的消费者
PUT /customers/{id}：更新某个具体的消费者信息（全量更新）
PATCH /customers/{id}：更新某个具体的消费者的信息（部分更新）
DELETE /customers/{id}：删除某个具体的消费者

// 有联系的资源之间的处理
GET /customers/{id}/orders：获取某个具体消费者的订单列表
...

请求参数
Query
url?后面的参数，存放请求接口的参数数据。

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

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

公共参数
APP 端请求

network		网络					WIFI、4G
operator	运营商				中国联通/移动
platform	平台					iOS、Android
system		系统					ios 13.3、android 9
device		设备型号				iPhone XR、小米9
udid		设备唯一标示	
apiVersion	API 版本号			v1.1、v1.2

WEB 端请求

appKey	授权Key	字符串

调用方需向服务方申请 appKey（请求时使用） 和 secretKey（加密时使用）。

安全规范
敏感参数加密处理

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

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

code		Number	结果码	成功=1、失败=-1、未登录=401、无权限=403
showMsg		String	显示信息	系统繁忙，稍后重试
errorMsg	String	错误信息	便于研发定位问题
data		Object	数据	JSON 格式

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

{
    "code": 1,
    "showMsg": "success",
    "errorMsg": "",
    "data": {
        "list": [],
        "pagination": {
            "total": 100,
            "currentPage": 1,
            "prePageCount": 10
        }
    }
}

安全规范
敏感数据脱敏处理

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

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