Overview

The domain name of the BCE CDN API interface is http://cdn.baidubce.com. All interfaces use /v2 as the prefix. The interface specification follows the BCE standard, uses HTTP protocol communication and supports HTTP1.0/1.1. Support PUT, POST, GET and DELETE request methods of HTTP.

Authentication Mechanism

You can interact with Baidu AI Cloud by two means, including authentication method and anonymous method. For authentication method, you need to verify the identity of a request sender by using Access Key Id / Secret Access Key encryption method. Access Key Id (AK) is used to identify users, and Secret Access Key (SK) is a key used by users to encrypt authentication string and by Baidu AI Cloud to verify the authentication string, where SK must be confidential, which can only be known by users and Baidu AI Cloud.

When Baidu AI Cloud receives the user's request, the system will use the same SK and the same authentication mechanism to generate the authentication string, and compare with the authentication string contained in the user's request. If the authentication string is the same, the system considers that the user has the specified operation permission and performs relevant operations; if the authentication string is different, the system will ignore the operation and return the error code. For details of authentication mechanism, please see authentication mechanism.

Interface Use Specification

Normalized string

Generally, one string can include any Unicode character. In programming, this kind of flexibility will bring about numerous troubles. Therefore, the concept of "normalized string" is introduced. One normalized string only includes the percent-encoding characters and URI (Uniform Resource Identifier) unreserved characters. RFC 3986 stipulates that "URI non-reserved characters" include the following characters: Letters (A-Z, a-z), numbers (0-9), hyphen (-), dot mark (.), underline (_), tilde (~). The method to change any string into a normalized string is:

• To convert strings into UTF-8 encoded byte stream.
• To keep all "URI non-reserved characters" unchanged.
• To make the Percent-encoding specified in RFC 3986 once for the rest bytes, namely, two sexadecimal strings representing the byte value are behind one "%". All the letters are in upper case. Example: Original string: This is an example for test, Corresponding specification string: this%20is%20an%20example%20for%20%E6%B5%8B%E8%AF%95。

Coding Specification

• The parsable contents and all request/response body contents are currently encoded with UTF-8, and more encoding types will be supported in the future.

• At request, we should make UrlEncode for the following:

  • Objectname, and "/" should be ignored when UrlEncode is made for Resource.
  • Value of Querystring.
  • x-bce-copy-source(ignore “/ ").
  • User-defined Meta: Meta Value only supports visible ASCII characters. If other characters are required, it is recommended to use UrlEncode for processing.

Date and Time

There are various methods to express date and time. For the purpose of unification, unless there are conventions or corresponding specifications, all fields expressing date and time specified in the HTTP standard utilize GMT, and UTC time for other places expressing date and time. The users should follow ISO 8601, and the following restrictions are made:

• Fields expressing the date all utilize the YYYY-MM-DD format, e.g. 2014-06-01 which means June 1, 2014.
• Fields expressing time all utilize the hh:mm:ss format, with the capital letter Z added at the end, which means UTC time. E.g. 23:00:10Z means UTC time: 23:00:10.
• When the date and time is combined, the capital letter T is added between the two items, e.g. 2014-06-01T23:00:10z means UTC time: 23:00:10 on June 1, 2014.

Standard of Request Response Format

• HTTP request, Key of parameter in Querystring, in lower camel case. E.g. upLoadId, partNumber, etc.
• All user-defined metas are put in the Header in the form of x-bce-meta-*. The total size of user-defined Metas shouldn't exceed 2K. The Key of x-bce-meta-* is in lower case at the Server side.

E.g.: When the user uses the PutObject interface to upload x-bce-meta-DeMo:value, the Server side uses x-bce-meta-demo:value in lower case. When the user uses the GetObject interface, the return value of the Sever side is x-bce-meta-demo:value.

• Other Headers are defined in the form of x-bce-* except the standard Headers specified by RFC2616.
• Keys all utilize the lower camel case in all JSONs.
• Each request response contains the two Headers of x-bce-request-id and x-bce-debug-id.
• Related fields such as Date, Content-MD5, Content-Type, Content-Length in Headers should be subject to the restrictions of RFC 2616.

• According to the stipulations in the HTTP protocol, both MD5 and Base64 encoding should be performed for Content-MD5. The computation method of Content-MD5 is as follows:

  Content-MD5 = "Content-MD5" ":" md5-digest md5-digest = <base64 of 128 bit MD5 digest as per RFC 1864>

Idempotence

If a request timeout or internal server error occurs when the create interface is called, the user may try to resend the request. At this time, the user can avoid creating more resources than expected through the clientToken parameter, that is, to ensure the idempotence of the request.

Idempotence is based on clientToken, an ASCII string no longer than 64 bits usually placed in a query string such as http://bcc.bj.baidubce.com/v2/instance? clientToken=be31b98c-5e41-4838-9830-9be700de5a20.

If the user calls the creation interface with the same clientToken value, the server will return the same request result. Therefore, when the user encounters an error and retries, he can provide the same clientToken value to ensure that only one resource is created. If the user provides a used clientToken, but other request parameters (including queryString and requestBody) are different or even URL path is different, the error code of IdempotentParameterMismatch will be returned.

The clientToken is valid for 24 hours, subject to the last time when the server receives the clientToken. That is, if the client continuously sends the same clientToken, the clientToken will be valid for a long time.

Common Header

Public Request Header

Public Response Header

Error Code

Error message format

The error message except for the HTTP status code should simultaneously include the parameters in the Table below in the HTTP body. The contents are as follows:

E.g.:

{ 
    "code":"IllegalRequestUrl", 
    "message":"The requested url belongs to domain which is not under acceleration", 
    "requestId":" 81d0b05f-5ad4-1f22-8068-d5c9de60a1d7" 
} 

Public Error Code