接口规范

 

一、概述

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;
    }
}