原创

API接口设计规范

API 接口设计规范,目的是提供给研发人员做参考。规范是死的,人是活的,希望自己定的规范,不要被打脸。

一、路由命名规范

动作
前缀
备注
获取getget{XXX}
获取getget{XXX}List
新增addadd{XXX}
修改updateupdate{XXX}
保存savesave{XXX}
删除deletedelete{XXX}
上传uploadupload{XXX}
发送sendsend{XXX}

二、请求方式

请求方式描述
GET获取数据
POST新增数据
PUT更新数据
DELETE删除数据

三、请求参数

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设备唯一标示
apiVersionAPI 版本号v1.1、v1.2


WEB 端请求

参数说明备注
appKey授权Key字符串

调用方需向服务方申请 appKey(请求时使用) 和 secretKey(加密时使用)

五、安全规范

  • 敏感参数加密处理、 数据脱敏处理。
  • 登录密码、支付密码,需加密后传输,建议使用 非对称加密
  • 用户手机号、用户邮箱、身份证号、支付账号、邮寄地址等要进行脱敏,部分数据加 * 号处理。

六、返回参数

参数类型说明备注
codeNumber结果码

成功=1
失败=-1
未登录=401
无权限=403

showMsgString显示信息系统繁忙,稍后重试
errorMsgString错误信息便于研发定位问题
dataObject数据JSON 格式

七、签名设计

签名验证没有确定的规范,自己制定就行,可以选择使用 对称加密、 非对称加密、 单向散列加密等。

八、幂等性设计

我们无法保证接口的每一次调用都是有返回结果的,要考虑到出现网络异常的情况。
举个例子,订单创建时,我们需要去减库存,这时接口发生了超时,调用方进行了重试,这时是否会多扣一次库存?
解决这类问题有 2 种方案:
一、服务方提供相应的查询接口,调用方在请求超时后进行查询,如果查到了,表示请求处理成功了,没查到就走失败流程。
二、调用方只管重试,服务方保证一次和多次的请求结果是一样的。就需要服务方的接口支持幂等性

大致设计思路是这样的:

  • 调用接口前,先获取一个全局唯一的令牌(Token)

  • 调用接口时,将 Token 放到 Header 头中

  • 解析 Header 头,验证是否为有效 Token,无效直接返回失败

  • 完成业务逻辑后,将业务结果与 Token 进行关联存储,设置失效时间

  • 重试时不要重新获取 Token,用要上次的 Token

九、其他规范

  • 参数命名规范 建议使用驼峰命名,首字母小写。

  • requestId 建议携带唯一标示追踪问题。


正文到此结束
该篇文章的评论功能已被站长关闭