1.协议
API与用户的通信协议,总是使用HTTPS协议,确保交互数据的传输安全。
2.安全
为了保证接口接收到的数据不是被篡改以及防止信息泄露造成损失,对敏感数据进行加密及签名。
数据加密
api接口请求参数一律采用RSA进行加解密,在客户端使用公钥对请求参数进行加密,在服务端使用对数私钥据进行解密,防止信息泄露。
签名
为了防止请求数据在网络传输过程中被恶意篡改,对所有非查询接口增加数字签名,签名原串为对请求参数进行自然排序,通过私钥加签后放入sign参数中。
时间戳
api接口中增加时间戳timestamp字段,作用:固定时间范围内,减少同一请求被暴力调用的次数。
3.API版本控制
API的版本号统一放入URL。
https://api.example.com/v{n}/
v{n}n代表版本号,分为整形和浮点型
整形版本号:大功能版本发布形式;具有当前版本状态下的所有API接口,例如:v1,v2
浮点型:为小版本号,只具备补充api的功能,其他api都默认调用大版本号的API,例如v1.1,v1.2
4.API路径规则
在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词。名词尽量与数据库表格名对应。
例子:
https://api.example.com/v1/products https://api.example.com/v1/users https://api.example.com/v1/employees
5.HTTP请求方式
对于资源的具体操作类型,由HTTP动词表示。
常用的HTTP动词由下面四个(括号里是对应的SQL命令)。
GET(SELECT):从服务器取出资源。
POST(CREATE):在服务器新建一个资源。
PUT(UPDATE):在服务器更新资源。
DELETE(DELETE):从服务器删除资源。
例子:
GET/product:列出所有商品
POST/product:新建一个商品
GET/product/ID:获取某个指定商品的信息
PUT/product/ID:更新某个指定商品的信息
DELETE/product/ID:删除某个商品
GET/product/ID/purchase:列出某个指定商品的所有投资者
GET/product/ID/purchase/ID:获取某个指定商品的指定投资者信息
6.请求数据
公共请求参数
参数名称 | 参数类型 | 是否必填 | 最大长度 | 描述 | 示例 |
---|---|---|---|---|---|
charset | String | 是 | 10 | 请求使用的编码格式如:utf-8,gbk | utf-8 |
sign_type | String | 是 | 10 | 生成签名字符串所使用的算法类型 | RSA |
sign | String | 是 | 344 | 请求参数签名串 | djdu7dusufiusgfu |
timestamp | String | 是 | 14 | 发送请求的时间,格式:yyyyMMddHHmmss | 20180505121212 |
requestSource | String | 否 | 8 | 客户端请求来源APP WAP PC | APP |
token | String | 否 | 鉴权标识,用于登录判断 | ||
biz_content | String | 是 | 请求参数集合,除公共参数外所有请求参数 |
请求参数(biz_content)
参数名称 | 参数类型 | 是否必填 | 最大长度 | 描述 | 示例 |
---|---|---|---|---|---|
phone | String | 是 | 10 | 登录手机号 | 15088890908 |
phoneCode | String | 是 | 6 | 验证码 | 234567 |
7.返回数据
为了保障前后端的数据交互的顺畅,统一接口返回模板如下:
{ code:0000, data:{}, msg:'' }
code:接口的执行状态
0000:表示成功
其他:不太异常
Data接口的主数据
返回JSON对象
Msg信息
当code!=0000都应该有错误信息
8.非RESTful API需求
由于实际业务开展过程中,可能会出现各种的api不是简单的restful规范能实现的,因此需要一些api突破restful规范原则。
8.1页面级API
把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据。
例子:
api/v1/get-home-data返回首页用到的所有数据
此类API存在缺陷:只要业务需求变动,该api就需要跟着变更。
8.2自定义组合API
把当前用户需要在第一时间内容加载的多个接口合并成一个请求发送到服务端,服务端根据请求内容,一次性把所有数据合并返回,相比于页面级API,具备更高的灵活性,同时又能很容易实现页面级API功能。
规范
地址:api/v1/testApi
传入参数:
data:[ {url:'api1',type:'get',data:{}}, {url:'api2',type:'get',data:{}}, {url:'api3',type:'get',data:{}}, ]
返回数据
{ code:0000, msg:'', data:[ {code:0000,msg:'',data:[]}, {code:0000,msg:'',data:[]}, {code:0000,msg:'',data:[]}, ] }
9.API共建平台
RAP是一个GUI的WEB接口管理工具。在RAP中,可定义接口的URL、请求&响应格式等等。通过分析这些数据,RAP提供MOCK服务、测试服务等自动化工具。
9.1什么是RAP?
在前后端分离的开发模式下,我们通常需要定义一份接口文档来规范接口的具体信息。如请求地址、有几个参数、参数名称及类型含义等等。RAP首先方便团队录入、查看和管理这些接口文档,并通过分析结构化的文档数据,重复利用并生成自测数据、提供自测控制台等等。
9.2RAP的特色
通过RAP来管理API文档。
提供MOCK服务,通过MockJS创建mock测试数据。