提供给第三方的业务接口应该如何设计呢?需要从哪些方面考虑?以及如何实现这些方面?
1、标准化
RESTful
2、安全性
1)请求token(防止接口被第三方调用)
token作为调用系统的凭证。token可以设置一次有效(安全性最高,完全防止接口被第三方调用),不过推荐设置时效性,减少获取获取token接口的请求频率。 token建议放在请求头上,这样可以跟业务参数完全区分开。
获取token一般会涉及的几个参数:appId、appKey、timestamp、nonce(requestId)、sign
appId和appKey通过开发平台申请和下发,appId即应用Id,是请求方的全局唯一的标识,一个appId对应一个客户,appKey需要高度保密,用于接口加密时拼装appKey作为加密串,不作为网络传输。
timestamp是时间戳,目的是为了减轻DOS攻击。防止请求被拦截后一直尝试请求接口。服务器设置时间戳阀值(5s),如果请求时间戳和服务器时间超过阀值,则响应失败。
nonce(requestId)是随机值,目的是为了增加sign的多变性,也可以保护接口的幂等性,相邻的两次请求nonce不允许重复,如果重复则认为是重复提交,响应失败。(将每次请求的nonce参数存储到缓存中,每次请求去缓存中查询是否存在,如果存在则认为是非法请求)
sign是参数签名,将appId,nonce,timestamp,还有其余非空请求参数,按照字母升序排列,然后使用URL键值对的格式(key1=value1&key2=value2)拼接起来,最后再拼接上appKey,组成待签名串;然后进行md5加密生成签名(或其他不可逆加密方式(如RSA2),有的情况要求先对待签名串进行UrlEncode,然后再加密生成签名)
请求携带appId和sign,只有拥有合法的身份appId和正确的签名sign才放行。
2)客户端IP白名单(防止接口被第三方调用)
为了提高应用访问的安全性。开发者可以通过IP白名单功能设置能够合法访问服务端API的IP列表(获取API访问凭证相关接口除外),不在IP白名单列表中的来源IP的请求会被拒绝。
输入的IP地址应为IPv4格式,不能为IP通配符,必须为公网服务器IP
3)加密签名(加密防止隐私数据泄露,签名防止数据被篡改)
对敏感入参进行AES加密,防止数据泄漏
对所有请求参数拼装后进行RSA签名,防止参数遭篡改。请求进来之后先验证签名,签名不匹配直接返回失败
(对于客户端与服务端的交互,AES密钥应使用动态密钥,每次由客户端生成AES密钥,并使用公钥进行加密传给服务端(RSA私钥保存在服务端))
4)限流
限流是为了更好的维护系统稳定性。防止接口遭恶意大量频繁调用(盗刷)。使用Redis进行接口调用次数统计,ip+接口地址作为key,访问次数作为value,每次请求value+1,设置过期时长来限制接口的调用频率。
可使用阿里的Sentinel限流工具:https://github.com/alibaba/Sentinel
3、幂等性
幂等性是指任意多次请求的执行结果和一次请求的执行结果所产生的影响相同。
如查询删除是幂等的,新增修改是非幂等的。
解决方案:
服务方提供一个生成全局唯一随机数token的接口,客户端在调用业务接口前先向服务方发送请求获取token,在客户端获取token的时候,将token存入redis中。
① 服务方提供获取token的接口,token可以是uuid
② 客户端在调用业务接口前先调用接口获取token
③ 服务方在客户端获取token时,生成token,并将token 作为 key,客户端用户信息作为value,保存在redis中,然后返回token
④ 客户端请求业务接口时,将获取的token放在header(最好放在header中)或者作为请求参数请求接口
⑤ 服务端收到请求后,从headers中拿到token,然后根据token到redis中查找该key是否存在
⑥ 如果存在,业务处理成功后,从redis中删除此token。如果不存在,说明重复调用,返回请勿重复操作即可
注意:从redis中查询token和删除token,要保证原子性,应使用redis分布式锁
javascript:void(0)
4、规范标准
1)加密、签名方式规范
敏感字段采用AES加密,模式为CBC,具体算法为 AES/CBC/PKCS5Padding。
签名的作用:对数据进行签名后,可以保证数据完整性,机密性和发送方角色的不可抵赖性,可以有效防止请求信息信息被篡改
签名方式采用RSA2(签名算法为SHA256WithRSA,要求RSA密钥的长度至少为2048位),步骤如下:
1)筛选并排序
获取所有请求参数,不包括字节类型参数(如文件,字节流),剔除sign参数和值为空的参数,并且参数名和参数值前后不要带有空格,并按照参数名的第一个字符的键值ASCII码递增排序(字母升序排序),如果遇到相同字符则按照第二个字符的键值 ASCII 码递增排序,以此类推;
2)拼接
将排序后的参数与其对应值,组合成“参数=参数值”的格式,并且把这些参数用 & 字符连接起来,此时生成的字符串为待签名字符串
3)签名
最后对待签名串签名,并进行BASE64编码。然后将生成的签名赋值给sign参数,拼接到请求参数中
2)请求方式为POST
除了sign参数外,其他参数全部以JSON格式放在body中。
请求方需要对sign进行UrlEncode,且Content-Type:application/json; charset=utf-8
3)接口返回规范
返回类型为JSON格式,包含状态码code、描述msg、响应数据data,返回码和描述提前定义好。必要的话,对响应的参数进行签名赋值给sign参数一并返回。
4)统一参数校验和验签,打印请求日志
使用AOP全局记录请求日志(请求接口URL,请求参数),响应日志。设置请求线程号,用于快速定位异常请求位置,排查问题原因
使用另一个AOP统一进行参数非空校验、签名校验、token校验,不通过直接返回失败,不进入业务代码。
5、接口设计示例
如何调用API
1、请求参数
请求头:这部分参数需要放在 HTTP 请求的 Header 中,主要包含调用 API 所需要使用的访问凭证(access token)以及 HTTP Content-Type(除获取凭证外其余接口:Content-Type:application/json; charset=utf-8)
请求体:POST请求的请求参数以JSON格式放在请求body中
查询参数:这部分参数需要在URL后后使用?进行连接,多个查询参数间以&分隔
注意:POST请求的sign参数放在请求URL中。如:https://api_host/api_path?sign=xxx'
2、API调用流程
①、申请 partnerId,partnerKey
partnerId:分配的合作方唯一的标识符
partnerKey:需要合作方高度保密,用于接口加密时拼装partnerKey作为加密串
②、获取API调用所需要的凭证
补充:凭证即接口准入性校验,已知接口准入性校验方式有:
access_token
ip白名单
签名机制
③、将凭证放在请求头,调用API接口
3、API调用方式
调用API接口时,需要使用 HTTPS 协议、JSON 数据格式、UTF8 编码。请求需要把访问凭证 access token 放到 Header 的 Authorization 中。
$ curl -X POST 'https://api_host/api_path?sign=xxx'
-H 'Authorization:<这里替换为对应的access token>'
-H 'content-type:application/json; charset=utf-8'
-d '{
"field": "value"
}'
4、API响应结果
API 的响应体结构包括 code、msg、data 三个部分
code为返回码,msg为返回信息,data为 API 的调用结果。默认请求成功时,code 为 0000,msg 为 success。data 在一些操作类 API 的返回中可能不存在,如:
{
"code": 0,
"msg": "success",
"data": {
// 响应的具体数据内容
}
}
5、返回码说明
获取访问凭证接口
①、概述:要访问API,需要先获取相应的访问凭证(access_token),作为API调用时的鉴权,在调用内容推送API时,被调用方可据此识别调用方的身份
②、说明:access_token具有一定的时效性,默认最长有效期为3600秒,在需要的情况下,合作方需要调用此接口来获取一个新的access_token
③、请求URL/Method
④:请求参数
⑤:响应参数
示例:
{
"code": 0,
"msg": "success",
"data": {
"access_token":"c83a2e753d41494fbde7b4aa31f4fa66",
"expires_in":"7200"
}
}
总结:
对于与外部的数据同步,如接入合作方的媒资数据
需要同时有全量和增量两种方式:
全量:看双方谈判,一方推全量或者一方拉全量即可
增量:增量推
对于数据接入方,最好的方式是拉全量、对方推增量的方式
全量按天或周的频率拉取
增量对方有更新及时推送过来,如果合作方不愿意,也可以我们主动去拉增量