约定

更新: 2020-03-18

1. 字符编码

调用API请求中使用到的参数和返回结果中的字符编码都为 UTF-8

2. 请求方式

接口支持两种方式发送 POST 请求

JSON 方式

请求header指定 Content-Type

Content-Type: application/json

请求body为JSON

{
  "client_id": "xxx",
  "name": "xxx",
  "dateline": 1584436337,
  "sign": "xxx"
}

x-www-form-urlencoded 方式

请求header指定 Content-Type

Content-Type: application/x-www-form-urlencoded

将参数和值使用 key1=val1&key2=val2 的方式组合放在请求body中, 每个参数的值都必须进行rfc3986URL编码, 如

filename=文档1.docx
filesize=1873470

组合后的请求body

filename=%E6%96%87%E6%A1%A31.docx&filesize=1873470

3. 返回结果

• 通常请求处理返回的内容为 JSON 格式
• 处理成功返回的 HTTP STATUS 为 200, 204 或 206
• 处理异常返回的 HTTP STATUS >= 400, 异常的返回:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Content-Length: 47

{"error_code":40104,"error_msg":"签名错误"}

注意: 如果使用经过封装的HTTP请求库, 服务端返回处理异常可能会导致抛出 Exception

• PHP 的 Guzzle 库, 使用默认参数初始化 Client, 当返回 HTTP STATUS >= 400 时将抛出 Exception, 因此需要在初始化时指定 http_errors 为 false:

$client = new GuzzleHttp\Client(['http_errors' => false]);

• C# 的 HttpWebRequest 在处理 HTTP STATUS >= 400 时也会抛出 WebException

public static HttpWebResponse GetHttpResponse(this HttpWebRequest request)
{
    HttpWebResponse response = null;

    try
    {
        response = (HttpWebResponse)request.GetResponse();
    }
    catch (WebException ex)
    {
        if (ex.Status == WebExceptionStatus.ProtocolError)
        {
            response = (HttpWebResponse) ex.Response;
        }
        else
        {
            throw;
        }
    }

    return response;
}