You can call Dynamic Route for CDN (DCDN) API operations by sending an HTTP GET requests to the DCDN API server. Such requests are completed by adding the relevant request parameters in the requests according to the interface instructions. Results will be returned based on the processing status of the requests.

Request structure

Endpoint

The DCDN API endpoint is cdn.aliyuncs.com.

Protocols

You can send requests over HTTP or HTTPS. For security, we recommend that you use HTTPS.

Request methods

You can call an API operation by sending an HTTP GET request. If you use this method, the request parameters must be included in the request URL.

Request parameters

The operation to be performed must be specified for each API request, which means that you must specify the Action parameter (such as DescribeDcdnService). Each request for an operation must contain common and operation-specific request parameters.

Encoding

Requests and responses are encoded using the UTF-8 character set.

Common parameters

Common request parameters

Common request parameters are shared by each API.
Name Type Required Description
Format String No The type of returned value. The returned value can be displayed in JSON or XML format. The default format is XML.
Version String Yes The API version, with a date format of YYYY-MM-DD. The current version is 2018-01-15.
AccessKeyId String Yes The secret key ID issued to a user by Alibaba Cloud. It is used to access services.
Signature String Yes The signature result string. For more information about signature calculation methods, see the signature mechanism description.
SignatureMethod String Yes The signature method. Currently, HMAC-SHA1 is supported.
Timestamp String Yes The request timestamp. The date format follows the ISO8601 standard and UTC time is used. The format is YYYY-MM-DDThh:mm:ssZ, for example, 2018-05-10T12:00:00Z (for 20:00:00 on Tuesday, January 15, 2018 Beijing Time).
SignatureVersion String Yes The signature algorithm version. The current version is 1.0.
SignatureNonce String Yes The unique random number. This is used to prevent replay attacks. Each random number can be used for only one request.

Common response parameters

The system returns a unique identification code (RequestId) for each API request, regardless of whether the API operation is successfully called.

Sample responses in XML format
  1. <?xml version=”1.0 encoding=”UTF-8”?><!—Result root node—><Interface name+response> <!—Request response tag—> <RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId> <!—Response data—></Interface name+response>
Sample responses in JSON format
  1. {“RequestId”: 4C467B38-3910-447D-87BC-AC049166F216”,/ Response data /}

Responses

The response data for API requests is displayed in a uniform format. In the response data, an HTTP status code of 2xx indicates that the API operation has been successfully called. An HTTP status code of 4xx or 5xx indicates that the API operation has not been successfully called.

The response data for successfully called API operations is returned mostly in XML or JSON format. You can add parameters to an API request to specify the format of the response data. The XML format is used by default.

The response examples in this section have been formatted with line breaks or indents for a clear view. The actual responses are not properly formatted as these examples.

Successful response examples

XML format(A response in XML format includes the service data and result of the API request.)
  1. <?xml version=”1.0 encoding=”UTF-8”?><!—Result root node—><Interface name+response> <!—Request response tag—> <RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId> <!—Response data—></Interface name+response>
JSON format
  1. { RequestId”: 4C467B38-3910-447D-87BC-AC049166F216”, / Response data /}

Error response examples

If you experience an error when calling API operations, no response data will be returned. The API operation caller can locate the cause of the error by referring to the appendix <Error Code Table>.

When an error occurs on an HTTP request for calling an API operation, an HTTP status code of 4xx or 5xx is returned. The returned message body includes important information such as the error code, RequestId, and HostId. RequestId uniquely identifies the request and HostId indicates the ID of the site that you accessed with the request. The caller can contact Alibaba Cloud customer service when the cause of the error cannot be found. We recommend that the caller provide HostId and RequestId to help us resolve the issue at the earliest opportunity.

XML format
  1. <?xml version=”1.0 encoding=”UTF-8”?><Error><RequestId>8906582E-6722-409A-A6C4-0E7863B733A5</RequestId> <HostId>dcdn.aliyuncs.com</HostId> <Code>UnsupportedOperation</Code> <Message>The specified action is not supported.</Message></Error>
JSON format
  1. { RequestId”: 8906582E-6722-409A-A6C4-0E7863B733A5”, HostId”: dcdn.aliyuncs.com”, Code”: UnsupportedOperation”, Message”: The specified action is not supported.”}

Sign signatures

Introduction

The DCDN service requires identity authentication for each request. Therefore, you must include the signature information in HTTP requests or HTTPS requests. By using Access Key ID and Access Key Secret, the DCDN performs symmetric encryption to identify and verify who is sending a request. Access Key ID and Access Key Secret are issued by Alibaba Cloud to visitors. They can be applied for and managed through the official Alibaba Cloud website.
Note Access Key ID indicates the identity of the visitor and Access Key Secret is the secret key used to encrypt the signature string and to verify the signature string on the server. They must be kept strictly confidential and only be known to Alibaba Cloud and the user.
Perform the following steps to sign a request.
  1. Use request parameters to construct a canonicalized query string.
    1. To construct a canonicalized query string, sort all request parameters by name in alphabetic order. The request parameters include common request parameters and customized parameters for the API request, but exclude the Signature parameter in “Common request parameters.”
      Note When you use the GET method to submit a request, the request parameters are included as a part of the URI. The request parameters in the URI are between the question mark (?) and the ampersand (&).
    2. Encode each parameter name and value. URL encode parameter names and values based on the UTF-8 character set. The URL encoding rules are described as follows:
      1. Do not encode any of the following characters: A-Z, a-z, 0-9, hyphen (-), underscore (_), period (.), and tilde (~).
      2. Percent encode all other characters with %XY, where X and Y are hex characters 0-9 and uppercase A-F. For example, English double quotation marks (“) are encoded as %22.
      3. Percent encode extended UTF-8 characters in the form %XY%ZA….
      4. Percent encode the English space character as %20. Do not percent encode the space character as a plus sign (+).
        Note Most libraries that support URL encoding, such as java.net.URLEncoder, comply with the encoding rules for the “application/x-www-form-urlencoded” MIME type. If this encoding method is used, replace the plus signs (+) in the encoded strings with %20, the asterisks (*) with %2A, and %7E with a tilde (~) to conform to the encoding rules.
    3. Separate the encoded parameter names from their encoded values with equal signs (=).
    4. Sort the parameter name and value pairs connected by equal signs (=) in alphabetical order and separate them with ampersand signs (&).
  2. Based on the created canonicalized query string, construct a string used for signature calculation based on the following rule:
    1. StringToSign=HTTPMethod + “&” +percentEncode(“/”) + ”&” +percentEncode(CanonicalizedQueryString)

    In this example, HTTPMethod indicates the HTTP method that is used to submit a request, for example GET.

    percentEncode(“/“) is the encoded value (“%2F”) of a forward slash (/). The encoding follows the URL encoding rules described in 2.b.

    percentEncode(CanonicalizedQueryString) is the encoded string of the canonicalized query string constructed in 1.b. It is created by following the URL encoding rules described in 2.b.

  3. Use the previous signature string to calculate the HMAC value of the signature as defined by RFC 2104. The Key used for signature calculation is the Access Key Secret of the user with an ampersand (&) added at the end. The corresponding number of an ampersand (&) is 38 in ASCII codes. The SHA1 hashing algorithm is used.
  4. Encode the HMAC value into a string according to Base64 encoding rules. You can then obtain the signature value.
  5. Add this signature value to the request parameters as the value of the Signature parameter. You have now completed the request signing process.
    Note When the obtained signature value is submitted to the DCDN server as the final request parameter value, it must undergo URL encoding like other parameters according to RFC3986 rules.
    Using DescribeDcdnService as an example, the request URL before signing is:
    1. http://dcdn.aliyuncs.com/?SignatureVersion=1.0&Format=JSON&Timestamp=2018-01-15T02:19:46Z&AccessKeyId=testid&SignatureMethod=HMAC-SHA1&Version=2018-01-15&Action= DescribeDcdnService &SignatureNonce=9b7a44b0-3be1-11e5-8c73-08002700c460
    After the signature, the StringToSign is as follows:
    1. GET&%2F&AccessKeyId%3Dtestid&Action%3D DescribeDcdnService &Format%3DJSON&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3D9b7a44b0-3be1-11e5-8c73-08002700c460&SignatureVersion%3D1.0&Timestamp%3D2018-01-15T02%253A19%253A46Z&Version%3D2018-01-15
    If we assume the Access Key Id is “testid”, Access Key Secret is “testsecret”, and the Key used for calculating HMAC value is “testsecret&”, the calculated signature value is as follows:
    1. KkkQOf0ymKf4yVZLggy6kYiwgFs=

Sample code

Signature Mechanism_python_sdk (Click here to download.)

Signature Mechanism_java_sdk (Click here to download.)