API 接口管理 架构 api接口设计

提供给第三方的业务接口应该如何设计呢？需要从哪些方面思量？以及如何实现这些方面？
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 中。

1. $ curl -X POST 'https://api_host/api_path?sign=xxx'
2. -H 'Authorization:<这里替换为对应的access token>'
3. -H 'content-type:application/json; charset=utf-8'
4. -d '{
5.         "field": "value"
6. }'

复制代码

　　4、API相应结果
　　API 的相应体布局包括 code、msg、data 三个部分
　　code为返回码，msg为返回信息，data为 API 的调用结果。默认哀求成功时，code 为 0000，msg 为 success。data 在一些操作类 API 的返回中大概不存在，如：

1. {
2.   "code": 0,
3.   "msg": "success",
4.   "data": {
5.     // 响应的具体数据内容
6.   }
7. }

复制代码

5、返回码说明

获取访问凭据接口
　　　　①、概述：要访问API，需要先获取相应的访问凭据（access_token），作为API调用时的鉴权，在调用内容推送API时，被调用方可据此识别调用方的身份
　　　　②、说明：access_token具有一定的时效性，默认最长有用期为3600秒，在需要的情况下，互助方需要调用此接口来获取一个新的access_token
　　　　③、哀求URL/Method

④：哀求参数 

⑤：相应参数

　　 
　示例：

1. {
2.   "code": 0,
3.   "msg": "success",
4.   "data": {
5.     "access_token":"c83a2e753d41494fbde7b4aa31f4fa66",
6.     "expires_in":"7200"
7.   }
8. }

复制代码

总结：
对于与外部的数据同步，如接入互助方的媒资数据需要同时有全量和增量两种方式：
   全量：看双方会商，一方推全量或者一方拉全量即可
   增量：增量推对于数据接入方，最好的方式是拉全量、对方推增量的方式全量按天或周的频率拉取增量对方有更新及时推送过来，如果互助方不乐意，也可以我们自动去拉增量
 

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。