1. Introduction

This guide introduces how to use CDNetworks API with the API-key authentication and describes the product description and API calling method.

2.Request Method

• Authentication Method
  • Authenticating Requests with API-Key Authentication
• Communication Protocol:
  • Support both HTTP and HTTPS
  • Recommend HTTPS for a higher level of security.
• HTTP Request methods:
  • Support POST, GET, PUT and DELETE

3. Common Parameters

Request parameters:

Response parameters:

4. Authentication Method

Authentication information must be contained in API requests no matter whether either HTTP or HTTPS protocol is used in submitting these API requests,

as Our system platform required identity authentication for each request to the interface.

In calling the interface, users need enter {user:password} and {Date header}(or x-cnc-date header).

The password is created with the GMT format of the date(for example, Thu, 10 Oct 2013 09:12:20 GMT) and the apikey(can be configured in Console -> IAM ->Account Management-> API Information -> API Security Management) issued by our system platform by the following method:

The following shows the Calculation method for password

password=Base64(HMAC-SHA1(UTF-8(API Key), UTF-8(Date)))

1. Date and api-key have to be in UTF-8 encoding;
2. The encryption algorithm used is Hash SHA1;
3. The generated encrypted value is encoded with Base64 to generate the password. (For example, Qp7RBYI792wnpm/OFXK/DqeldAk=)

Our system platform compares the {Date} (or x-cnc-date header) in the interface requests with the local time of the platform. If the time difference is over 15 minutes, the request is ignored to avoid resending of the expired message. Then get the password with the same encryption method and compare it with the user’s password. Requests with matched passwords are allowed and are denied if otherwise.

5. Add X-TimeZone Header

In order to adjust GMT Time Zone on the API response, please use the X-Time-Zone header.
X-Time-Zone Header is effective for time-relevant values of API response. It is not effective for time-relevant parameters of API requests.

Precaution: Some API support simple-timestamp format or UTC-supported time format. Please read the API specification and check the timestamp format as required

The following shows examples of XML format comparing GMT+8 and GMT+9.

#!/bin/bash
username="example_username"
apiKey='example_apiKey'
date=`env LANG="en_US.UTF-8" date -u "+%a, %d %b %Y %H:%M:%S GMT"`
password=`echo -en "$date" | openssl dgst -sha1 -hmac $apiKey -binary | openssl enc -base64`
curl -i --url "https://api.cdnetworks.com/api/report/domainhit?datefrom=2018-10-01T00:00:00%2B08:00&dateto=2018-10-01T00:05:00%2B08:00&type=fiveminutes" \
-X "POST" \
-u "$username:$password" \
-H "Date: $date" \
-H "Accept: application/xml" \
-H "X-TIME-ZONE:GMT+09:00"  \
-d '<?xml version="1.0" encoding="utf-8"?>
<domain-list>
  <domain-name>www.example.com</domain-name>
</domain-list>'

curl -i --url "https:// api.cdnetworks.com /api/report/domainhit?datefrom=2018-10-01T00:00:00%2B08:00&dateto=2018-10-01T00:05:00%2B08:00&type=fiveminutes" \
-X "POST" \
-u "$username:$password" \
-H "Date: $ndate" \
-H "Accept: application/xml" \
-H "X-TIME-ZONE:GMT+08:00"  
-d '<?xml version="1.0" encoding="utf-8"?>
<domain-list>
  <domain-name> www.example.com</</domain-name>
</domain-list>'


          

The following shows the results of XML format comparing GMT+8 and GMT+9.

HTTP/1.1 200 OK 
Server: openresty/1.11.2.2
Date: Wed, 12 Dec 2018 05:11:11 GMT
Content-Type: application/xml;charset=utf-8
Content-Length: 166
Connection: keep-alive
X-Time-Zone: GMT+09:00
x-cnc-request-id: 5969ca0c-4641-4407

<?xml version="1.0" encoding="UTF-8"?>
<hit-report>
<hit-summary>0</hit-summary>
<hit-data><timestamp>2018-10-01 01:05:00</timestamp><hit>0</hit>
</hit-data>
</hit-report>

HTTP/1.1 200 OK 
Server: openresty/1.11.2.2
Date: Wed, 12 Dec 2018 05:11:12 GMT
Content-Type: application/xml;charset=utf-8
Content-Length: 166
Connection: keep-alive
X-Time-Zone: GMT+08:00
x-cnc-request-id: ad46aa1b-e8dc-43fe

<?xml version="1.0" encoding="UTF-8"?>
<hit-report>
<hit-summary>0</hit-summary><hit-data>
<timestamp>2018-10-01 00:05:00</timestamp>
<hit>0</hit></hit-data>
</hit-report>

6.Code Examples

shell：Download
Java：Download
Python：Download
PHP：Download
Go：Download
.Net：Download
The sample code is for reference only, please use it according to the actual situation.

7.Response Formats

Success results
Success results are provided below. both JSON and XML are supported.

The following shows an example of JSON:

HTTP/1.1  {2xx}
Date: Fri, 26 Oct 2012 06:33:26 GMT
Content-Type: application/xml;charset=utf-8
x-cnc-request-id:{id string auto generated by cloud server}  /* globally unique requestid */
{
  /* data of returned results  */
}
          

The following shows an example of XML:

HTTP/1.1   {2xx}
Date: Fri, 26 Oct 2012 06:33:26 GMT
Content-Type: application/xml;charset=utf-8
x-cnc-request-id:{id string auto generated by cloud server}  /* globally unique requestid */

<?xml version="1.0" encoding="UTF-8"?>
<!—results root-->
  <!—data of returned results-->
</!—results root-->

8.Error response cases

Results data is not returned if the error occurred in calling the interface Error cause can be positioned with “Error codes”.

If an error occurred, the HTTP request returns a 4xx or 5xx status code.

The returned message contains the specific error code and error details. Besides, the request header also contains the globally unique ID: RequestId. If the error cause cannot be specified, please contact technical support and provide the RequestId to facilitate the tracking process.

The following shows an example of JSON:

HTTP/1.1   {4xx or 5xx}{error such as Access Denied or InternalError}
Date: Fri, 26 Oct 2012 06:33:26 GMT
Content-Type: application/xml;charset=utf-8
x-cnc-request-id:{id string auto generated by cloud server}  /* globally unique requestid */

{
    "code": "{the error   code, like MissingDateHeader}",
    "message": "{description, like Authorized request must have a Date or x-cnc-date header }"
}
      

The following shows an example of XML:

HTTP/1.1   {4xx or 5xx}{error such as Access Denied or InternalError}
Date: Fri, 26 Oct 2012 06:33:26 GMT
Content-Type: application/xml;charset=utf-8
x-cnc-request-id:{id string auto generated by cloud server}  /* this requestid is unique globally */

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <code>{the error code, like MissingDateHeader}</code>
  <message>{description, like Authorized request must have a Date or x-cnc-date header}</message>
</response>
          

9. Error Code