General Description

API calls follow the HTTP protocol, and different regions are assigned different domain names. The specific domain name follows the pattern bcc.{region}.baidubce.com. For example: bcc.bj.baidubce.com. The data exchange format is JSON, and all request and response body contents are encoded in UTF-8.

Certification

Users who use the BCC API need to complete certification. Those who have not passed certification can go to the certification under security certification in the Baidu Open Cloud Official Website Console for certification. Users who have not passed certification will receive the following error prompt code:

Error code	Error description	HTTP status code	Chinese explanation
QualifyNotPass	The User has not pass qualify.	403	The account has not passed certification

API authentication mechanism

The Access Key and request signature mechanism are uniformly adopted for all API security authentication. Access Key consists of an Access Key ID and a Secret Access Key, both of which are strings. For each HTTP request, use the algorithm described below to generate a authentication string. Submit the certification string in the Authorization header. The server verifies the correctness of the authentication string based on the generation algorithm. The certification string format is bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}.

• The version is a positive integer.
• The timestamp refers to the UTC time when the signature is created.
• The expirationPeriodInSeconds specifies the duration during which the signature remains valid.
• SignedHeaders includes the list of headers involved in the signature algorithm. The headers are separated by semicolons (e.g., host;x-bce-date) and arranged in lexicographical order. (This API signature involves only the host and x-bce-date headers.)
• The signature is a 256-bit signature represented as a 64-character lowercase hexadecimal digest.

When Baidu AI Cloud receives a user's request, the system uses the same SK and certification mechanism to generate a certification string. This string is then compared with the one included in the user's request. If the two match, the system confirms the user has the required permissions and proceeds with the operation. If they differ, the system cancels the operation and returns an error code.

For detailed information on the certification mechanism, please refer to [Certification](Reference/Authentication mechanism/Introduction.md).

Communication protocol

The BCC API supports both HTTP and HTTPS methods. For improved data security, using HTTPS is recommended.

Request structure description

The data exchange format is JSON, and all request and response body content is encoded in UTF-8.

Request parameters include the following 4 types:

Parameter type	Description
URI	It is usually used to specify the operation entity, such as: POST /v{version}/instance/{instanceId}
Query	Request parameters carried in the URL
HEADER	It is passed in through HTTP header fields, such as: x-bce-date
RequestBody	Request data body organized in JSON format

Response structure description

Response values are in two forms:

Response content	Description
HTTP STATUS CODE	Such as 200, 400, 403, 404, etc.
ResponseBody	Response data body organized in JSON format.

API version number

Parameters	Types	Parameter location	Description	Required or not
version	String	URL parameter	API version number: The current value is 2.	Yes

Idempotence

When invoking the creation API, if a timeout or an internal server error occurs, the user can retry the request. In such cases, the clientToken parameter ensures no extra resources are created, thereby maintaining the request's idempotence.

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

If the same clientToken value is used when calling the creation API, the server will return the same result. If a retry is necessary due to an error, supplying the same clientToken ensures that only one resource is created. If the clientToken has been used previously but other parameters like queryString, requestBody, or even the URL Path differ, an error code of IdempotentParameterMismatch will be issued.

The clientToken remains valid for 24 hours from the last time it was received by the server. In cases where the same clientToken is continuously sent, it will stay valid indefinitely within that time window.

Password encryption transmission specification

All API parameters involving passwords must be encrypted, and plaintext transmission is strictly prohibited. Passwords are encrypted using the AES 128-bit encryption algorithm, with the first 16 bits of the SK serving as the key. The binary byte stream generated post-encryption must be converted into a hexadecimal format and transmitted to the server as a string. The steps are as follows:

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

Date and time regulations

There are multiple ways to represent date and time. For uniformity, unless it is conventional or there are corresponding specifications, UTC time shall be used wherever date and time need to be expressed, following ISO 8601, with the following constraints:

1. Dates shall be expressed in the YYYY-MM-DD format, for example, 2014-06-01 represents June 1, 2014
2. Time should be written in the hh:mm:ss format followed by an uppercase letter Z, which denotes UTC time. For example, 23:00:10Z equates to 23:00:10 UTC.
3. When combining date and time, use a capital letter T to separate them. For example, 2014-06-01T23:00:10Z signifies 23:00:10 UTC on June 1, 2014.

Normalized string

A string can typically include any Unicode character. However, this flexibility may lead to complications in programming. To address this, the concept of a “normalized string” is introduced. A normalized string includes only percent-encoded characters and URI (Uniform Resource Identifier) unreserved characters.

According to RFC 3986, URI unreserved characters consist of the following: letters (A-Z, a-z), digits (0-9), hyphens (-), dots (.), underscores (_), and tildes (~).

The way to convert any string into a normalized string is:

• Convert the string into a UTF-8 encoded byte stream.
• Leave all unreserved URI characters unchanged.
• Perform percent-encoding as described in RFC 3986 for the remaining bytes. Use a % symbol followed by two uppercase hexadecimal characters representing the byte value.

Example:

Original string: this is an example for testing, Corresponding normalized string: this%20is%20an%20example%20for%20%E6%B5%8B%E8%AF%95.

Typesetting conventions

Typesetting format	Meaning
< >	Variable
[ ]	Optional
{ }	Mandatory
|	Mutually exclusive relationship
Monospace font Courier New	Screen output