OpenAPI通用规范说明

EasyOpenAPI产品作为所有子服务开放API的统一管理服务，对于子服务开放的API进行统一管理和调用，达到用户使用同一套标准可以调用不同子服务的API，提升开发效率，满足更多元化的业务场景需要。

该文档为调用接口时的通用规范，对所有OpenAPI都适用，必读！OpenAPI列表与详情请查看OpenAPI目录下各个子产品的OpenAPI文档说明。

一、调用相关

1.1 支持协议与请求

所有OpenAPI仅支持HTTP协议，支持的请求为GET、POST。

1.2 请求地址

请求地址由三个部分组成，分别是openapi统一入口域名、子产品调用前缀、子产品功能URI。例如：

http://easy-openapi.bdms.service.163.org/openapi/easydataservice/api/v1/app/get

其中http://easy-openapi.bdms.service.163.org 为统一入口域名，/openapi/必写，easydataservice为需要调用的子产品名，/api/v1/app/get为子产品功能URI。其中子产品调用前缀部分里的子产品名称参考1.2.2响应码中的子产品对照表，子产品功能URI请参考每个子产品详细调用文档。

PS: easyops环境中的统一入口域名获取方式，可打开easyops界面，找到EasyOpenAPI项目打开url，新开页面的地址前缀即为统一入口域名。

1.3 请求参数

• GET请求：

当调用的接口为GET方法时，请求参数只能放置在调用地址的URL中。

http://easy-openapi.bdms.service.163.org/openapi/easydataservice/app/v1/app/get?user=user@163.com&product=product1&appName=app1&authType=AKSK&timestamp=xxxxx&accessKey=yyyyy&sig=zzzzzz

• POST请求：

当调用的接口为POST方法时，请求参数只能以json格式(请求头中需要指定Content-Type: application/json)放置在Request Body。

http://easy-openapi.bdms.service.163.org/openapi/easydataservice/api/v1/app/add -d '{"user": "user@163.com", "product": "product1", "appName": "app1", "appDesc":"xxxxxxxxxxxx", "authType":"AKSK", "timestamp":1232423123, "accessKey":"yyyyy", "sig":"zzzzzz"}'
{
    "参数1"："值1"，
    "参数2"："值2"
}

1.4 鉴权

目前支持的鉴权方式有：AK/SK。

• AS/SK鉴权： 系统为调用者分别应用身份，每个应用都有唯一的accessKey和secretKey。在使用aksk鉴权方式时，需要在入参中携带authType(值为AKSK)、timestamp(5分钟内的毫秒时间戳)、accessKey、sig(由secretKey计算出)。

GET方法时，以上参数放在uri中，例如：

&authType=AKSK&timestamp=1646813499000&accessKey=
2709c24f97ce463c84b7ce9ee7a92212&sig=818dc0bb904cc75fa935cb96e0fc9473

POST方法时,以上参数放在request body里，例如：

{
    "authType":"AKSK",
    "timestamp":1646813499000,
    "accessKey":"2709c24f97ce463c84b7ce9ee7a92212",
    "sig":"818dc0bb904cc75fa935cb96e0fc9473"
}

其中sig的计算方法为：

sig = md5(secretKey+timestamp) 其中+号表示拼接操作，sig为小32位

Java代码工具类：

public class MD5MsgDigest {

    /**
     * notice:认为raw string是utf8编码
     */
    public static String digest(String rawString) {
        return digest(rawString, "utf-8");
    }

    public static String digest(String rawString, String charset) {
        Charset cs = Charset.forName(charset);
        try {
            return compute(rawString, cs);
        } catch (Exception e) {
            return "";
        }
    }

    /**
     * Computes the MD5 fingerprint of a string.
     * 
     * @return the MD5 digest of the input <code>String</code>
     */
    private static String compute(String inStr, Charset charset) throws Exception {
        MessageDigest md5 = MessageDigest.getInstance("MD5");
        byte[] md5Bytes = md5.digest(inStr.getBytes(charset));
        return toHexString(md5Bytes);
    }

    public static String toHexString(byte[] bytes) {
        StringBuffer hexValue = new StringBuffer();
        for (int i = 0; i < bytes.length; i++) {
            int val = ((int) bytes[i]) & 0xff;
            if (val < 16) {
                hexValue.append("0");
            }
            hexValue.append(Integer.toHexString(val));
        }
        return hexValue.toString();
    }
}

//计算sig
Long timestamp = System.currentTimeMillis();
String sig = MD5MsgDigest.digest(secretKey+timestamp);

其他编程语言也有类似md5工具类，请自行查找。

1.5 文件上传接口

涉及到文件上传的openAPI，请求路径前缀上稍有区别，需在统一前缀openapi后加file-upload，如下所示：

http://{openapi域名}}/openapi/file-upload/{子产品调用前缀}/子产品功能URI}

文件上传接口的入参为multipart/form-data格式，不支持application/json。

1.6 文件下载接口

涉及到文件下载的openAPI，请求路径前缀上稍有区别，需在统一前缀openapi后加file-download，如下所示：

http://{openapi域名}}/openapi/file-download/{子产品调用前缀}/子产品功能URI}

文件流通过HttpServletResponse获取。

二、响应相关

2.1 响应格式

2.2 响应码

业务异常码前缀与子产品对照表