Agreements and Conventions

Update: 2020-03-18

This document provides guidelines and conventions for interacting with the API. It includes details on character encoding, request formats, and handling responses, especially error scenarios.

1. Character Encoding

All parameters and results used in API requests should be encoded in UTF-8.

2. Request Methods

The API supports POST requests in two different formats:

JSON Format

For requests using JSON, specify the Content-Type in the request header as:

Content-Type: application/json

The request body should be in JSON format, for example:

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

x-www-form-urlencoded Format

For requests using x-www-form-urlencoded, specify the Content-Type in the request header as:

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

The parameters and values should be combined using the key1=val1&key2=val2 format in the request body. Each parameter value must be URL encoded following rfc3986 standards. For example:

• Original parameters:

  filename=doc1.docx
  filesize=1873470
  

• Encoded and combined request body:

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

3. Response Handling

Successful Responses

• Typically, the content returned from a successful request will be in JSON format.
• The HTTP STATUS codes for successful responses include 200 (OK), 204 (No Content), or 206 (Partial Content).

Error Responses

• For error responses, the HTTP STATUS code will be >= 400.

• Error responses will also be in JSON format. Example of an error response:

  HTTP/1.1 401 Unauthorized
  Content-Type: application/json
  Content-Length: 47
  
  {"error_code":40104,"error_msg":"签名错误"}
  

Note on Exception Handling in HTTP Libraries

When using HTTP request libraries, be aware that a server-side error might throw an Exception. Here are specifics for some commonly used libraries:

PHP - Guzzle

By default, the Guzzle client will throw an exception when it encounters an HTTP status code >= 400. To handle these without throwing an exception, disable http_errors:

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

C# - HttpWebRequest

The HttpWebRequest class will throw a WebException when it encounters an HTTP status code >= 400. To handle this, you can catch the exception and check the status:

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