API 接口设计规范
概述
这篇文章分享 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 | 删除数据 |
请求参数
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
}
}
}
安全规范
敏感数据脱敏处理
用户手机号、用户邮箱、身份证号、支付账号、邮寄地址等要进行脱敏,部分数据加 * 号处理。
其他规范
- 属性名命名时,建议使用驼峰命名,首字母小写。
- 属性值为空时,严格按类型返回默认值。
- 金额类型/时间日期类型的属性值,如果仅用来显示,建议后端返回可以显示的字符串。
- 业务逻辑的状态码和对应的文案,建议后端两者都返回。
- 调用方不需要的属性,不要返回。
签名设计
签名验证没有确定的规范,自己制定就行,可以选择使用 对称加密
、非对称加密
、单向散列加密
等,分享下原来写的签名验证,供参考。
日志平台设计
日志平台有利于故障定位和日志统计分析。
日志平台的搭建可以使用的是 ELK
组件,使用 Logstash
进行收集日志文件,使用 Elasticsearch
引擎进行搜索分析,最终在 Kibana
平台展示出来。
幂等性设计
我们无法保证接口的每一次调用都是有返回结果的,要考虑到出现网络异常的情况。
举个例子,订单创建时,我们需要去减库存,这时接口发生了超时,调用方进行了重试,这时是否会多扣一次库存?
解决这类问题有 2 种方案:
一、服务方提供相应的查询接口,调用方在请求超时后进行查询,如果查到了,表示请求处理成功了,没查到就走失败流程。
二、调用方只管重试,服务方保证一次和多次的请求结果是一样的。
对于第二种方案,就需要服务方的接口支持幂等性。
大致设计思路是这样的:
- 调用接口前,先获取一个全局唯一的令牌(Token)
- 调用接口时,将 Token 放到 Header 头中
- 解析 Header 头,验证是否为有效 Token,无效直接返回失败
- 完成业务逻辑后,将业务结果与 Token 进行关联存储,设置失效时间
- 重试时不要重新获取 Token,用要上次的 Token
小结
限流设计、熔断设计、降级设计,这些就不多说了,因为大部分都用不到,当用上了基本上也都在网关中加这些功能。
暂时就想到这么多,规范这东西不是一成不变的,发现有不妥的及时调整吧。
你们接口的输入输出 Key,命名是用驼峰还是下划线?欢迎留言。
推荐阅读
API 接口设计规范的更多相关文章
- restFull api接口
RestFull api接口 前后端分离开发的接口规范 什么是RestFull 是目录比较流行的api设计规范 注:restfull api规范应用场景,前后端分离的项目中 数据接口的现场 例如: / ...
- 如何设计一个牛逼的API接口
在日常开发中,总会接触到各种接口.前后端数据传输接口,第三方业务平台接口.一个平台的前后端数据传输接口一般都会在内网环境下通信,而且会使用安全框架,所以安全性可以得到很好的保护.这篇文章重点讨论一下提 ...
- 干货来袭-整套完整安全的API接口解决方案
在各种手机APP泛滥的现在,背后都有同样泛滥的API接口在支撑,其中鱼龙混杂,直接裸奔的WEB API大量存在,安全性令人堪优 在以前WEB API概念没有很普及的时候,都采用自已定义的接口和结构,对 ...
- 12306官方火车票Api接口
2017,现在已进入春运期间,真的是一票难求,深有体会.各种购票抢票软件应运而生,也有购买加速包提高抢票几率,可以理解为变相的黄牛.对于技术人员,虽然写一个抢票软件还是比较难的,但是还是简单看看123 ...
- 快递Api接口 & 微信公众号开发流程
之前的文章,已经分析过快递Api接口可能被使用的需求及场景:今天呢,简单给大家介绍一下微信公众号中怎么来使用快递Api接口,来完成我们的需求和业务场景. 开发语言:Nodejs,其中用到了Neo4j图 ...
- web api接口同步和异步的问题
一般来说,如果一个api 接口带上Task和 async 一般就算得上是异步api接口了. 如果我想使用异步api接口,一般的动机是我在我的方法里面可能使用Task.Run 进行异步的去处理一个耗时的 ...
- HTTP API接口安全设计
HTTP API接口安全设计 API接口调用方式 HTTP + 请求签名机制 HTTP + 参数签名机制 HTTPS + 访问令牌机制 有没有更好的方案? OAuth授权机制 OAuth2.0服务 ...
- Postman - 功能强大的 API 接口请求调试和管理工具
Postman 是一款功能强大的的 Chrome 应用,可以便捷的调试接口.前端开发人员在开发或者调试 Web 程序的时候是需要一些方法来跟踪网页请求的,用户可以使用一些网络的监视工具比如著名的 Fi ...
- H3 BPM引擎API接口
引擎API接口通过 Engine 对象进行访问,这个是唯一入口. 示例1:获取组织机构对象 this.Engine.Organization.GetUnit("组织ID"); 示例 ...
随机推荐
- POJ 2456 Aggressive cows (二分)
题目传送门 POJ 2456 Description Farmer John has built a new long barn, with N (2 <= N <= 100,000) s ...
- Qt中设置窗口图标
转:https://blog.csdn.net/weiren2006/article/details/7438028 1.通过qtcreator新建一个文件filename.qrc,将图片添加到fil ...
- 打造m3u8视频(流视频)下载解密合并器(kotlin)
本文是对我原创工具m3u8视频下载合并器关键代码解析及软件实现的思路的讲解,想要工具的请跳转链接 1.思路说明 思路挺简单,具体步骤如下: 下载m3u8文件 解析m3u8文件获得ts文件列表 根据文件 ...
- Adaboost和随机森林
在集成学习中,主要分为bagging算法和boosting算法.随机森林属于集成学习(Ensemble Learning)中的bagging算法. Bagging和Boosting的概念与区别该部分主 ...
- 数学基础系列(六)----特征值分解和奇异值分解(SVD)
一.介绍 特征值和奇异值在大部分人的印象中,往往是停留在纯粹的数学计算中.而且线性代数或者矩阵论里面,也很少讲任何跟特征值与奇异值有关的应用背景. 奇异值分解是一个有着很明显的物理意义的一种方法,它可 ...
- stars-one原创工具——蓝奏云批量下载工具
一款可以批量下载蓝奏云分享的文件夹下的所有文件 基于HtmlUnit和okhttp开源库,所以打包后的jar包文件有点大 蓝奏云下载地址 github地址 需求 之前找电子书资源的时候,网友分享的蓝奏 ...
- matplotlib 折线图
1.基本要点 # 导入模块 from matplotlib import pyplot as plt # x轴数据 x = range(2, 26, 2) # y轴数据 y = [15, 13, 14 ...
- python scoket
一.简介 scoket(套结字)在python就是模块 二.分类 基于文件型(不用) 基于网络型 名字:AF_INET AF_INET6 三.scoket应用 1.基于tcp 长连接:基于tcp的Se ...
- css 透明度
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8& ...
- 前端之css的基本使用(一),行内、内部、外部样式,语法格式、注释、选择符、属性等
一.行内.内部.外部样式 1.行内样式 <!DOCTYPE html> <html lang="en"> <head> <meta cha ...