分享公司使用的数仓api接口文档模板

修改记录

1 文档说明

本文档旨在为第三方应用需求方访问数据中台开放服务提供统一的Http接口调用规范和说明。

2 适用对象

本规范适用于数据中台的各个需求方发起的调用请求，POST提交数据或GET请求数据。

3 名词解释

APPID：appid是开放平台APP的唯一标识，在公众平台申请接入应用后，中台会自动分配对应的appid，用于标识该应用。Appsecret：AppSecret是APPID对应的接口密码，用于生成加密签名。

4 接口说明

4.1 接口地址

使用前需要测试接口地址网络是否开通，若未开通，请申请域名的网络访问权限，由项目经理提交集团运维开通。

4.2 请求方式

GET, application/x-www-form-urlencoded;charset=utf-8

4.3 请求参数

系统级参数

以下参数是数据中台系统定义的，此类参数是各个应用接入方必传的参数，数据服务才可正常提供服务。中台采用授权认证接口方式，接入应用初始时申请应用appID,和参数签名秘钥api_secret;

业务级参数

业务级参数是对应的接口根据业务设置的请求参数，在接口请求中需要系统级参数+业务级参数共同使用请求api方可。

4.4 参数签名

参数签名生成算法（Java版）如下，其他语言可以根据注释说明完成对应版本。

/**
     * 生成签名信息
     * @param secretKey  产品私钥
     * @param params  接口请求参数名和参数值map，不包括signature参数名
     * @return
     * @throws UnsupportedEncodingException
     */
public static String genSignature(String secretKey, Map<String, String> params) throws UnsupportedEncodingException {
    // 1. 参数名按照ASCII码表升序排序
    String[] keys = params.keySet().toArray(new String[0]);
    Arrays.sort(keys);
    StringBuilder stringBuilder = new StringBuilder();
    // 2. 按照排序拼接参数名与参数值
    for (String key : keys) {
        stringBuilder.append(key).append(params.get(key) == null ? "" : params.get(key));
    }
    // 3. 将secretKey拼接到最后
    stringBuilder.append(secretKey);

    // 4. MD5是128位长度的摘要算法，用16进制表示，一个十六进制的字符能表示4个位，所以签名后的字符串长度固定为32个十六进制字符。
    return DigestUtils.md5Hex(stringBuilder.toString().getBytes("UTF-8"));
}

注：产品秘钥是数据中台分配给接入应用方的secretKey，上述算法返回的结果便是系统级参数的参数签名。

4.5 响应数据包格式

响应数据的格式为json格式，输出内容编码格式是UTF-8

4.6 结果返回

成功返回

示例数据：

{
    "data": [
        {
            "id":1,
            "name":'营运经理',
            "createdate":'2011-11-30 00:00:00',
            "status":0,
        },
        {
            "id":2,
            "name":'销售经理',
            "createdate":'2011-11-30 00:00:00',
            "status":0,
        }
    ],
    "errorCode": 200,
    "errorMessage": "正常",
    "pageNo": 1,
    "pageSize": 1,
    "success": true,
    "totalCount": 2
}

失败返回

示例数据：

{
  "errorCode":220001,
  "errorMessage":"没有该API的资产访问权限",
  "success":false
}

4.7 错误码定义

5 接口列表

5.1 测试api

功能说明

测试api

接口地址

/test/testsink

请求参数

返回参数

当返回结果为成功时，success为true时，data参数中会有以下返回结果参数:

返回数据示例

{
    "data":[
        {
            "name":"liqi",
            "id":1
        },
        {
            "name":"zhaowu",
            "id":2
        },
        {
            "name":"wangwu",
            "id":2
        },
        {
            "name":"lisi",
            "id":3
        },
        {
            "name":"zhangsan",
            "id":10
        }
    ],
    "errorCode":200,
    "errorMessage":"正常",
    "pageNo":1,
    "pageSize":10,
    "success":true,
    "totalCount":6
}

喜欢就关注我们吧！

关注作者公众号，回复关键字 "api模板" 即可获取word版本