通用接口开放平台设计与实现——（3）API服务总体设计_通用接口设计

API服务是通用接口平台的主体部分，对外暴露Restful风格的数据接口，其他应用系统通过调用API服务，一方面，可以查询权限范围内的业务数据，另一方面，可以将自身系统产生的数据推送过来。

API服务的技术实现相对消息服务而言，难度较低，注意事项也比较少，这里先放一个整体设计，细节后面在消息服务后面再展开介绍。

总体设计

API服务分为服务技术框架和具体业务功能接口两部分，技术框架部分负责统一调度、数据验证、身份认证、安全控制、日志记录等职责，具体业务功能接口负责实际的业务接口功能处理，总体处理流程如下图所示：

交互技术

接口传输协议：HTTP
接口请求方式：POST
数据编码格式：UTF-8
数据传输格式：JSON
​

输入参数

API服务接口输入参数有且只有5个参数，如下表：

前面4个为系统参数，不能为空。
最后1个参数为业务参数，所有跟业务相关的数据都封装在该参数中。
​

输出参数

API服务接口返回参数有4个参数，如下表：

执行结果如为Success，则代表成功，可进一步从业务数据字段data获取返回的业务数据，如为Error，则代表接口执行出错， errorCode和errorMessage字段中存放错误编码和错误信息。

安全控制

身份认证

通用接口平台会为调用系统分配一个应用标识和密钥，调用系统在调用API服务时，传入应用标识，使用密钥对参数进行签名，将签名作为请求参数传入，通过签名来完成身份认证。

防篡改

通用接口平台会为调用系统分配一个密钥，调用系统使用该密钥，通过特定的加密算法，对请求参数进行加密，生成签名，将签名作为请求的一部分，传给通用接口平台。通用接口平台收到请求后，以同样的算法进行签名，对比二者是否相同，如不相同，则说明传递过程中发生了数据篡改，拒绝进行服务。

时效性控制

为了控制API服务调用的时效性，避免一个请求被截取后，此请求会不断的有效，通用接口平台设置了请求的有效时间为600秒，以调用系统传入的请求时间参数与服务器当前时间进行比对，10分钟范围内的请求视为合法请求，超出该范围视为非法请求，拒绝服务。
​

签名算法

签名生成过程如下：
1.对所有请求参数（除去sign签名参数自身），根据参数编码的ASCII码表的顺序排序。
2.依序拼装参数编码和参数值，形成一个字符串，每组参数编码与参数值中间使用=连接
3.把拼装好的字符串前后拼接应用密钥
4.使用MD5签名算法对编码后的字节流进行运算。
5.将运算得到的字节流结果使用十六进制表示，转换为全部大写
最后产生的是一个32位长度的16进制数
注意：密钥仅参与签名的生成的运算过程，不能放到参数列表中。
​

错误定义

系统级错误定义如下:

业务级错误定义参见各具体的API服务接口。