The API calling conforms to the HTTP protocol. Each region uses different domain names, and the specific domain name is bcc.{region}.baidubce.com. The data exchange format is JSON, and all contents of request/response body are encoded in UTF-8.

Identity Verification

The real name authentication is required for users who use BCC API. Users who fail to pass the real name authentication can go to the "Identity Verification" under the security authentication in the Baidu AI Cloud Official Website Console for the authentication. Users who fail to pass the real name authentication obtain an error code.

Error Code	Error Description	HTTP Status Code	Explanations
QualifyNotPass	The User has not pass qualify.	403	The account number does not pass the real name authentication.

API Verification Mechanism

Access Key and request signature are used for all API security authentication. The Access Key consists of an Access Key ID and a Secret Access Key, and both of them are strings. For each HTTP request, an authentication string is generated with the algorithm described below. Submit tge authentication string in Authorization header field. The server should verify the correctness of the authentication string based on the generation algorithm. The format of the authentication string is bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}.

• The “version” number is a positive integer.
• "Timestamp" is the UTC time when the signature is generated
• “ExpirationPeriodInSeconds” indicates the expiration date of the signature.
• “SignedHeaders” is the list of header fields involved in the signature algorithm The header domain names are separated by semicolons (;), such as host; X-bce-date. The list is in lexicographic order. (API signature only uses two headers of host and x-bce-date)
• "signature" is a hexadecimal representation of a 256-bit signature, and consists of 64 lowercase letters.

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 it with the authentication string contained in the user's request. If the authentication string is identical to that contained in the user’s request, the system considers that the user has the specified operation privilege to perform the relevant operation. If the authentication string is different, the system ignores the operation and returns the error code.

For details on the authentication mechanism, see Authentication Mechanism.

Communication Protocol

BBC API supports the HTTP and HTTPS calling methods. To improve data security, it is recommended to use HTTPS.

Request Structure Description

The data exchange format is JSON, and all contents of request/response body are encoded in UTF-8.

The request parameters include the following 4 types:

Parameter Type	Description
URI	It is usually used to indicate the operation entity, such as POST /v{version}/instance/{instanceId}.
Query parameters	Request parameters carried in the URL
HEADER	Parameters passed via HTTP header field, such as, x-bce-date
RequestBody	Request data body organized in JSON format

Response Structure Description

The response value includes two forms:

Returned Contents	Note
HTTP STATUS CODE	Such as 200, 400, 403, 404
ResponseBody	Response data body organized in JSON format

API Version Number

Parameters	Type	Parameter Position	Description	Required
version	String	URL parameter	API version number, whose current value is 2.	Yes

Idempotence

If the user encounters a request timeout or an internal error of the server when calling the creation interface, the user may try to resend the request. In this case, the user avoids creating more resources than expected via the clientToken parameter, that is to guarantee the idempotency of the request.

The idempotency is based on clientToken, which is an ASCII string with a length of up to 64 bits and is usually placed in a query string, such as http://bcc.bj.baidubce.com/v1/instance?clientToken=be31b98c-5e41-4838-9830-9be700de5a20.

If a creation interface is called with the same clientToken value, the server will return the same request result. So, in case of an error, the creation interface can be re-called with the same clientToken value, to ensure that only one source can be created. If a used clientToken is provided, but other request parameters (including queryString and requestBody) are different and even url Path is different, IdempotentParameterMismatch error code will be returned.

ClientToken is valid for 24 hours, and that the last time the clientToken was received by the server is considered to be standard. That is to say, if the client sends the same eclientToken constantly, this clientTokem will be valid in a long time.

Password Encryption and Transmission Specification

All interface parameters involving password need to be encrypted and plaintext transmission is prohibited. All passwords is encrypted with AES 128-bit encryption algorithm, and with the first 16 bits of SK as the key. The binary byte stream generated after encryption is converted to the hexadecimal and transmitted to the server in the form of string. The specific steps are as follows:

• byte[] bCiphertext= AES (plaintext, SK)
• String strHex = HexStr(bCiphertext)

Date and Time Specification

There are many ways to represent the date and time. For unification, unless it is established by convention or has corresponding specifications, UTC time shall be adopted everywhere where date and time are required, ISO 8601 shall be followed, and the following restrictions shall be made:

1. The date is indicated in the form of YYYY-MM-DD. For example, 2014-06-01 represents June 1, 2014.
2. The time is indicated in the form of hh: mm: ss, and an upper case Z is added at the end to indicate the UTC time. For example, 23:00:10Z represents PM 23:00:10 UTC time.
3. When it involes the combined indication of date and time, an upper case T is added between date and time. For example, 2014-06-01T23:00:10Z represents PM 23:00:10 UTC time on June 1, 2014.

Normalized String (UrlEncode)

A string can usually contain any Unicode character. This flexibility brings a lot of trouble during programming. Therefore, Baidu AI Cloud introduces the concept of normalized string. A normalized string contains the percent-encoding characters and URI (Uniform Resource Identifier) unreserved characters only .

RFC 3986 specifies that the URI unreserved characters include the letters (A-Z, a-z), numbers (0-9), hyphen (-), period (.), underline (_) and wavy line (~).

The method to convert any string into a normalized string is as follows:

• Converts a string into a UTF-8-encoded byte stream.
• All URI unreserved characters remain unchanged.
• The percent-encoding specified in RFC 3986 is performed for other bytes, i.e., one % is followed by two hexadecimal letters indicating this byte value. All letters are upper case.

Example:

The original string:this is an example for test, the corresponding normal string:this%20is%20an%20example%20for%20%E6%B5%8B%E8%AF%95

Agreed Typesetting

Typesetting Format	Significance
< >	Variable
[ ]	Optional
{ }	Required
|	Mutex relationship
Monospaced font, Courier New	Screen output