Call Method

CDN API interfaces are called by sending an HTTP GET request to the CDN API server. Such requests are completed by adding the relevant request parameters in the request according to the interface instructions. Results will be returned based on the request’s processing status.

Request structure

Service address

The CDN API service access address is cdn.aliyuncs.com.

Communication protocol

The system supports request communication through HTTP or HTTPS channels. In order to ensure the security of the request, we recommended that you send requests through an HTTPS channel.

Request methods

The system supports the sending of HTTP GET requests. For this method, the request parameters must be included in the request URL.

Request parameters

For each request, the operation to be executed must be specified, namely the Action parameter (for example, CreateCDNServer), and each operation must contain the public request parameters and the specific request parameters of the specified operation.

Character encoding

Requests and returned results both use UTF-8 character set encoding.

Common parameters

Public request parameters

Public request parameters refer to the request parameters that need to be used by every interface.

Request example:

https://cdn.aliyuncs.com/?Format=xml&Version=2013-01-10&Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D&SignatureMethod=HMAC-SHA1&SignatureNonce=15215528852396&SignatureVersion=1.0&AccessKeyId=key-test&Timestamp=2012-06-01T12:00:00Z

Common return parameters

Each time the user sends a call request to an interface, no matter whether it is successful or not, the system will return a unique identification code (RequestId) to the user.

Example of XML results returned:

<?xml version="1.0" encoding="UTF-8"?> 
<!—Result Root Node-->
<Interface Name+Response>
    <!—Return Request Tag-->
    <RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId>
    <!—Return Result Data-->
</Interface Name+Response>

Example of JSON results returned:

{
    "RequestId": "4C467B38-3910-447D-87BC-AC049166F216",
    /* Return Result Data*/
}

Returned results

After the API service is called, the returned data adopts a uniform format. A returned HTTP status code of 2xx indicates that the call was successful. A returned HTTP status code of 4xx or 5xx indicates that the call failed.

For successful calls, the primary formats of returned data is XML and JSON. When a request is sent, an external system can pass in parameters to specify the format of returned data. The default format is XML.

In this document, examples of results returned are formatted in a way that is easier for users to view. The actual results returned are not formatted with line breaks, indentation, etc.

Successful results

Example of the XML results returned:

Note: The XML results returned include a message stating whether the request was successful and the specific service data.

<?xml version="1.0" encoding="UTF-8"?> 
<!—Result Root Node-->
<Interface Name+Response>
    <!—Return Request Tag-->
    <RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId>
    <!—Return Result Data-->
</Interface Name+Response>

JSON example:

{
    "RequestId": "4C467B38-3910-447D-87BC-AC049166F216",
    /* Return Result Data*/
}

Error results

After an error is encountered in an interface call, no result data will be returned. The caller can refer to the table in the appendix to locate the cause of the error.

When an error occurs in a call, the HTTP request will return an HTTP status code of 4xx or 5xx. The returned message body includes the specific error code and error message. It also contains a globally unique request ID (RequestId) and the ID of the site (HostId) you accessed with this request. If unable to find the error cause, the caller can contact Alibaba Cloud customer service and provide the HostId and RequestId to help us solve the problem as quickly as possible.

XML example:

<?xml version="1.0" encoding="UTF-8"?>
<Error>
<RequestId>8906582E-6722-409A-A6C4-0E7863B733A5</RequestId>
   <HostId>cdn.aliyuncs.com</HostId>
   <Code>UnsupportedOperation</Code>
   <Message>The specified action is not supported.</Message>
</Error>

JSON example:

{
    "RequestId": "8906582E-6722-409A-A6C4-0E7863B733A5",
    "HostId": "cdn.aliyuncs.com",
    "Code": "UnsupportedOperation",
    "Message": "The specified action is not supported."
}

Signature mechanism

Detailed description

Each time it is accessed by a request, the CDN service will perform sender authentication. Therefore, whether HTTP or HTTPS protocol is used to submit the request, the request must contain signature information. By using the Access Key ID and Access Key Secret the CDN performs symmetric encryption to authenticate the request sender. The Access Key ID and Access Key Secret are officially issued to visitors by Alibaba Cloud (visitors can apply for and manage them on the official Alibaba Cloud website).

Where,

• The Access Key ID indicates the identity of the visitor.
• The Access Key Secret is the secret key used to encrypt the signature string and to verify the signature string on the server. It must be kept strictly confidential and only be known to Alibaba Cloud and the user.

When a user calls a server, the following method is used to sign the request:

a. The Canonicalized Query String is constructed using the request parameters.

• 1.The request parameters are ordered alphabetically by the parameter names (this includes the public request parameters and user-defined parameters for the given request interfaces described in this document, but not the Signature parameter mentioned in Public Request Parameters).

  Note: When a request is submitted using the GET method, these parameters are the parameter section of the request URI (that is, the section in the URI following ? and connected by &).

• 2.The name and value of each request parameter are encoded. The names and values must undergo URL encoding using the UTF-8 character set. The URL encoding rules are as follows:

  • The characters A~Z, a~z, 0~9, and “-“, “_”, “.”, “~” are not encoded.
  • Other characters are encoded in %XY format, with XY representing the characters’ ASCII code in hexadecimal notation. For example, the English double quotes (“) are encoded as %22.
  • Extended UTF-8 characters are encoded in %XY%ZA? format.

  • It must be noted that the English space is encoded as %20, rather than the plus sign (+).

    Note: Generally, libraries that support URL encoding (for example, Java’s java.net.URLEncoder) are all encoded according to the 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 change %7E back to the tilde (~) to conform to the encoding rules described above.

• 3.Connect the encoded parameter names and values with the English equal sign (=).

• 4.Then, order the parameter name and value pairs connected by equal signs in alphabetical order and connect them with & to produce the Canonicalized Query String.

b. Follow the rules below to construct the string used for signature calculation by using the Canonicalized Query String constructed in the previous step.

StringToSign=
HTTPMethod + “&” +
percentEncode(“/”) + ”&” +
percentEncode(CanonicalizedQueryString)

Here, HTTPMethod is the HTTP method used for request submission, for example, GET.

percentEncode(/) is the encoded value for the character / according to the URL encoding rules described in a.1, namely %2F.

percentEncode(CanonicalizedQueryString) is the encoded string of the Canonicalized Query String constructed in Step a.1, produced by following the URL encoding rules described in a.2.

c. According to RFC2104 definitions, use the above signature sting to calculate the signature’s HMAC value. Note: When calculating the signature, the Key is the “Access Key Secret” held by the user with the “&” character (ASCII:38) added on the end. The SHA1 hashing algorithm is used.

d. According to Base64 encoding rules, encode the above HMAC value into a string. This gives you the signature value.

e. Add the obtained signature value to the request parameters as the Signature parameter. This completes the request signing process.

Note: When the obtained signature value is submitted to the CDN server as the final request parameter value, it must undergo URL encoding like other parameters according to RFC3986 rules.

Using DescribeCdnService as an example, the request URL before signing is as follows:

http://cdn.aliyuncs.com/?SignatureVersion=1.0&Format=JSON&Timestamp=2015-08-06T02:19:46Z&AccessKeyId=testid&SignatureMethod=HMAC-SHA1&Version=2014-11-11&Action=DescribeCdnService&SignatureNonce=9b7a44b0-3be1-11e5-8c73-08002700c460

Thus, the StringToSign is:

GET&%2F&AccessKeyId%3Dtestid&Action%3DDescribeCdnService&Format%3DJSON&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3D9b7a44b0-3be1-11e5-8c73-08002700c460&SignatureVersion%3D1.0&Timestamp%3D2015-08-06T02%253A19%253A46Z&Version%3D2014-11-11

If we assume the ‘Access Key ID’ is “testid”, the ‘Access Key Secret’ is “testsecret”, and the Key used for HMAC calculation is “testsecret&”, the calculated signature value is:

KkkQOf0ymKf4yVZLggy6kYiwgFs=

The signed request URL is (note the added Signature parameter):

http://cdn.aliyuncs.com/?SignatureVersion=1.0&Format=JSON&Timestamp=2015-08-06T02%3A19%3A46Z&AccessKeyId=testid&SignatureMethod=HMAC-SHA1&Version=2014-11-11&Signature=KkkQOf0ymKf4yVZLggy6kYiwgFs%3D&Action=DescribeCdnService&SignatureNonce=9b7a44b0-3be1-11e5-8c73-08002700c460