接口规范

一、概述

UmsOpenAPI 是提供给客户应用/业务服务器调用。

二、约定

1.使用 HTTPS 协议作为基础的通讯协议， 采用 HTTPS 协议作为基础安全保障；
2.所有的 HTTP 请求使用 POST 方法；
3.请求参数和响应的结果均采用 UTF-8 编码的 JSON 结构 封装到消息体里； HTTP 请求的 Content-Type 头值为： "application/json; charset=utf-8"。
4.HTTP 请求 URL 的路径区分 API 接口； QueryParamter中必须有token变量， 标识调用者身份。
5.HTTP 请求的 Body 部分做为 API 接口的参数；不同的接口有不同的JSON对象定义。
6.HTTP答复的Body不是API接口结果， 总体格式为：
{
    "errorCode": 0, // 结果码，0: 成功，非0: 失败
    "data": null, // 返回数据对象，不同的接口有不同的定义
    "errorMessage": "success", // 结果描述
    "requestId":"xxxxxxxxxxxxxx-xxxxxxxxxxxx-xxxxxxxx", // 请求唯一ID
}
7.签名方法：
为了防止API调用过程中被黑客恶意篡改，调用任何一个API都需要携带签名，MUC服务端会根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。MUC目前支持的签名算法有：MD5(signMethod=md5)，签名大体过程如下：
• 对所有API请求参数（包括公共参数和业务参数，但除去sign参数和File, byte[]类型的参数），根据参数名称的ASCII码表的顺序排序。如：foo=1, bar=2, foo_bar=3, foobar=4排序后的顺序是bar=2, foo=1, foo_bar=3, foobar=4。
• 将排序好的参数名和参数值拼装在一起，根据上面的示例得到的结果为：bar2foo1foo_bar3foobar4。
• 把拼装好的字符串采用utf-8编码，使用签名算法对编码后的字节流进行摘要。如果使用MD5算法，则需要在拼装的字符串前后加上app的secret后，再进行摘要，如：md5(secret+bar2foo1foo_bar3foobar4+secret)；
• 将摘要得到的字节流结果使用十六进制表示，如：hex("helloworld".getBytes("utf-8")) = "68656C6C6F776F726C64"

StringUtils.java (签名方法)

import java.util.Arrays;
import java.util.Map;
import java.util.regex.Pattern;

import org.apache.commons.lang3.StringUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.util.DigestUtils;

public class SignUtils {
    private static Logger logger = LoggerFactory.getLogger(SignUtils.class);

    public static String getSign(Map<String, Object> map, String secret) {
        // 第一步：检查参数是否已经排序
        String[] keys = map.keySet().toArray(new String[0]);
        Arrays.sort(keys);

        // 第二步：把所有参数名和参数值串在一起
        StringBuilder query = new StringBuilder();

        query.append(secret);
        for (String key : keys) {
            String value = String.valueOf(map.get(key));
            query.append(key).append(value);
        }
        query.append(secret);

        // 第三步：计算签名
        String sign = DigestUtils.md5DigestAsHex(query.toString().getBytes());
        if (logger.isDebugEnabled()) {
            logger.info("\n--->signStr : " + query.toString() + "\n--->sign : " + sign);
        }

        return sign;
    }
}