API-Key Authentication

Last update:2023-03-06 14:52:39

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:

Request Header Required Description
Authorization Yes Authorization info, for example, user: password
Accept No Browser-acceptable MIME types , with json as the default returned format, such as 1. “Accept: application/json”, means the returned json format. 2. “Accept: application/xml”, means the returned xml format.
Content-Type Conditional What MIME category does the requested resource belong Notes: Needed when using POST or PUT method
Date Conditional Current local time, to calculate the field information of Authorization. The format should comply with RFC 1123 Specification, like Thu, 17 May 2012 19:37:58 GMT Notes: except x-cnc-date is used, or this field is compulsory.
x-cnc-date Conditional Current local time, to calculate the signature information of the Authorization field. When a Date cannot be set, this field can be used to set time. The format should comply with RFC 1123 Specification, like Thu, 17 May 2012 19:37:58 GMT
X-Time-Zone Conditional Time zone The format is the time zone offset representation relative to GMT, the regular constraint: ^GMT±:00$, the default value is GMT+ 08:00, for example, the East Eight Time Zone is GMT+08:00, and the West Eighth Zone is GMT-08:00; At the same time, it takes effect on the parameters of the entry and exit parameters; If the time parameter comes with a time zone, the time zone of the parameter itself is taken as the standard;

Response parameters:

Response Header Remarks
Accept MIME type that can be accepted by browsers
Content-Type What MIME category does the requested resource belong to; Notes: Needed when using POST or PUT method
Date The format should comply with RFC 1123 Specification, like Thu, 17 May 2012 19:37:58 GMT

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

HTTP status 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 frequency.
436 WPLUS_IPTooFrequence The ip is too frequency.
437 WPLUS_AccountCapacityFull The api capacity is full.
438 WPLUS_APiTooFrequence The api is too frequency.
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 frequence.
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 thd concurrency threshold.
450 WPLUS_DateError date is error.
453 WPLUS_HystrixSocketConnectTimeout hystrix socket connect timeout!
501 WPLUS_SystemError system error!
503 WPLUS_InvokeBackendFail invoke backend fail!
530 WPLUS_InvalidArgument exception occurred 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 call netty. Please try again.
555 WPLUS_HystrixSocketConnectError hystrix socket connect error!
Is the content of this document helpful to you?
Yes
I have suggestion
Submitted successfully! Thank you very much for your feedback, we will continue to strive to do better!