1. Introduction

This guide introduces how to use CDNetworks API with the AK/SK authentication(Access Key/Secret Key Authentication) and describes the product description and API calling method.

2.Request Method

• Authentication Method

  • Authenticating Requests with AK/SK authentication(Access Key/Secret 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

4. Common Parameters

Request parameters:

Request Header	Type	Required	Description
x-cnc-accessKey	string	Y	Your accessKey to call CDNetworks API
x-cnc-timestamp	int	Y	Timestamp in seconds If the time difference is over five minutes, the request will be unavailable.
Authorization	string	Y	HTTP Standard Authentication Header Field, for example “CNC-HMAC-SHA256 Credential=qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z, SignedHeaders=content-type;host,  Signature=5b73ebca11a738be44caa52179af87b4dccac4035fa363ebda4b8328eca3d21f” - CNC-HMAC-SHA256：Signature method, currently fixed using the value - Credential： The signed credentials,qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z Y x-cnc-accessKey； - SignedHeaders： Header information involved in signature calculation with content type and host as required heads; - Signature： Signed summary. Check credentials, calculated from all parameters, are detailed below in the signed computation process. Identical x-cnc-timestamp, within 5 min authorship does not allow for repetition
content-Type	string	Y	The type of data actually sent to the server.
host	string	Y	API endpoint .  e.g“ api.cdnetworks.com”

Response parameters:

Response Header	Description
Accept	Browser-acceptable MIME types
Content-Type	What MIME type the resource is requested, note: required when using POST and PUT methods
Date	Date Format comply with HTTP date formats according to RFC 1123 specifications as of Thu, 17 May 2012 19:37:58 GMT

Authorization Calculation Method

• Authorization = Algorithm + ’ ’ + ‘Credential=’ + AccessKey + ', ’ + ‘SignedHeaders=’ + SignedHeaders + ', ’ + ‘Signature=’ + Signature

Field Name	Description
Algorithm	Fixed Value “CNC-HMAC-SHA256”
AccessKey	AccessKeySecret in the key pair, obtained from the Console: Account Management → Basic Information → API Information Management → AccessKey Management page. The value in this example is qiVc3ieau1BlosMghauAhnBcjd2ceqcCC4Z.
SignedHeaders	See below for header information participating in the signature. This example sets the value to "content-type;host"
Signature	Signature value. The result of this sample calculation is “5b73ebca11a738be44caa52179af87b4dccac4035fa363ebda4b8328eca3d21f”.

Signature Calculation Procedure

• Signature=HexEncode(HMAC_SHA256(SecretKey, StringToSign));
• Stringtosign=Algorithm+\n+Timestamp+\n+Hash.SHA256(CanonicalRequest)

CanonicalRequest=
Method+’\n’+
RequestURI+’\n’+
QueryString+’\n’+
CanonicalHeaders+’\n’+
SignedHeaders+’\n’+
HashedRequestPayload

• HashedRequestPayload= Lowercase(HexEncode(Hash.SHA256(RequestPayload)))

1. Canonical Request

Spell the specification request string in the following pseudo-code format:（CanonicalRequest）：

CanonicalRequest =
    Method + '\n' +
    RequestURI + '\n' +
    QueryString + '\n' +
    CanonicalHeaders + '\n' +
    SignedHeaders + '\n' +
    HashedRequestPayload

Field	Description
Method	HTTP request method (get, post). The value of this example is get. Note that the characters here are upper case
RequestURI	URI parameter，such as /api/aksk/test
QueryString	The query string in the URL that initiates the HTTP request,The POST request was fixed to an empty string""， For the GET request, it was the content of the string after the question(?) mark in the URL (We need to decode this part)，for exampledecode("test=test&a=a").
CanonicalHeaders	The specific information of the header participating in the signature includes at least two headers: host and content type. You can also add a custom header to participate in the signature to improve the uniqueness and security of your request. Splicing rules: 1. The header key and value  are converted to lowercase, remove the leading and trailing spaces, and splice according to the format of key: value \n； 2. Multiple headers are spliced in ascending ASCII order of header key (lowercase).此The result of this calculation is “content-type:application/json\nhost:api.cdnetworks.com\n”. Note: the content type must be consistent with the actual sending. Some programming language network libraries will automatically add the charset value even if it is not specified. If the signature is inconsistent with the sending, the server will return the signature verification failure.
SignedHeaders	The header that participates in the signature indicates which headers participate in the signature of this request, and corresponds to the header specific information contained in canonicalheaders one by one. Content type and host are required headers. Splicing rules: 1. Turn the head key into lowercase; 2. Multiple header keys (lowercase) are spliced in ascending ASCII order with semicolons (;) separate. This example is “content-type;host”.
HashedRequestPayload	Hash value of the request body (i.e. payload or body). If the parameter is passed in the format of content type: application / JSON, the example is the hash value of {"test": "body"}; If the parameter is passed in the post request mode of content type: application / x-www-form-urlencoded, the example is the hash value of "test = body"; The calculation pseudo code is lowercase (hexencode (hash. SHA256 (requestpayload)), that is, SHA256 hash the HTTP request body, then hexadecimal encoding, and finally convert the encoding string into lowercase letters. For GET request，RequestPayload is empty strings. The result of this calculation is e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

Based on the above rules, the canonical request string obtained in the example is as follows:

GET
/api/aksk/test
test=test&a=a
content-type:application/json
host:api.cdnetworks.com


content-type;host
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

2. String To Sign

Spell the reception signature string in the following format:

StringToSign = Algorithm + \n + Timestamp + \n + HashedCanonicalRequest

Field Name	Description
Algorithm	Signature algorithm, it is currently fixed as “CNC-HMAC-SHA256”.
Timestamp	Request timestamp, which is the value of the common parameter x-cnc-timestamp in the request header, takes the current time UNIX timestamp, accurate to seconds. This example takes a value of 1631239486
HashedCanonicalRequest	The hash value of the specification request string obtained by the splicing of the preceding steps calculates a pseudocode of Lowercase(HexEncode(Hash.SHA256(CanonicalRequest))).The result of this example is “990b65d70886cbf13eef1a6bffdb695b53ea74e7ab150d77efc64acc464443e0”

Note: Timestamp must be current system time, and you need to ensure that system time and standard time are synchronized and fail if the difference is more than five minutes.
If you don’t synchronize with the standard time for a long time, you might run for a while and the request must fail, returning a signature expiration error.

Based on the above rules, the StringToSign string obtained in the example is as follows:

CNC-HMAC-SHA256
1631239486
990b65d70886cbf13eef1a6bffdb695b53ea74e7ab150d77efc64acc464443e0

3. Calculated Signature

1）Obtain a signature key, such as：

• SecretKey = test

Field Name/	Description
SecretKey	AccessKey Secret

2) Calculate the signature with the pseudocode as follows:

• Signature = HexEncode(HMAC_SHA256(SecretKey, StringToSign))

• Based on the above rules, the values obtained in the example are:

CNC-HMAC-SHA256 Credential=qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z, SignedHeaders=content-type;host, Signature=1b81bc8fec1058e2df8e5aa7526be348311d3fc97ab428464d833cf23cceb273

The final complete invocation information is as follows:

GET https://api.cdnetworks.com/api/aksk/test?test=test&a=a

Authorization: CNC-HMAC-SHA256 Credential=AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE, SignedHeaders=content-type;host, Signature=1b81bc8fec1058e2df8e5aa7526be348311d3fc97ab428464d833cf23cceb273
Content-Type: application/json;
Host: api.cdnetworks.com
x-cnc-accessKey: qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z 
x-cnc-timestamp: 1631239486

Code examples

Examples of Access Key codes are recommended:

• Python3 : Download
• Java: Download
• Go: Download

7.Response Formats

• Success results
  The success result shows as below. Samples of both JSON and XML are given.

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 API Error cause can be positioned with “Error codes”.

• If an error occurred, the HTTP error response has a 4xx or 5xx HTTP status code. The response messages contain the specific error code and error details.

• Besides, the request header also contains the globally unique ID: request-id. 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

HTTP Status Code	Code	Message
401	WPLUS_InvalidHTTPAuthHeader	The HTTP authorization header is bad
403	WPLUS_RequestTokenNotExistError	request token not exist or expired
431	WPLUS_MatchApiNone	there is no suitable api you request.
432	WPLUS_ApiPrivilegeError	the account used is not authenticated using this api.
434	WPLUS_RequestExpired	Request has expired.
435	WPLUS_AccountTooFrequence	The account is too frequent.
436	WPLUS_IPTooFrequence	The ip is too frequent.
437	WPLUS_AccountCapacityFull	The api capacity is full.
438	WPLUS_APiTooFrequence	The api is too frequent.
439	WPLUS_APiCapacityFull	The api capacity is full.
440	WPLUS_AccountWhitelist	remote ip not exist in account white list.
441	WPLUS_ApiWhitelist	remote ip not exist in api white list.
443	WPLUS_ApiUnactive	the api invoked is inactive.
446	WPLUS_AccountApiTooFrequence	The account to the indicated api is too frequency.
447	WPLUS_APiTooConcurrent	The api call exceeds the concurrent threshold.
448	WPLUS_AccountTooConcurrent	The account call exceeds the concurrent threshold.
449	WPLUS_AccountApiTooConcurrent	The account to the indicated API call is exceed the concurrency threshold.
450	WPLUS_DateError	date is error.
453	WPLUS_HystrixSocketConnectTimeout	hystrix socket connect timeout!
462	WPLUS_AuthorizationError	authorization is error! please check signature, accessKey!
501	WPLUS_SystemError	system error!
503	WPLUS_InvokeBackendFail	invoke backend fail!
530	WPLUS_InvalidArgument	exception occured when read body(InputStream) from HttpServletRequest.
533	WPLUS_CollectAgentMakeDirError	collectAgent call error:can not make folder.
534	WPLUS_CollectAgentMakeFileError	collectAgent call error:can not make file.
535	WPLUS_RunShellError	run shell error.
537	WPLUS_ProcessorHttpJobInvokerCallServiceError	We encountered an internal error in CommonJobInvoker when calling netty. Please try again.
555	WPLUS_HystrixSocketConnectError	hystrix socket connect error!