General Description

API interactions are conducted via the HTTP protocol. Data is exchanged in JSON format, with all request and response body content encoded in UTF-8.

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 authentication mechanism to generate an authentication string and compares it to the string included in the user's request. If the two strings match, the system confirms the user's permission to perform the operation and executes it. If they do not match, the system skips the operation and returns an error code.

For detailed information on the authentication mechanism, please refer to Authentication Mechanism.

Communication protocol

Both HTTP and HTTPS methods are supported. For better data security, it is recommended to use HTTPS.

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:

Response structure description

Response values are in two forms:

API version number

Idempotence

When calling the resource creation API, timeout or internal server errors may lead to repeated resource creation attempts. To prevent the unintended creation of extra resources, the clientToken parameter can be applied, ensuring the request remains idempotent.

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.

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:

• Date shall be expressed in the format of YYYY-MM-DD. For example, 2014-06-01 represents June 1, 2014.
• Time shall be expressed in the hh:mm:ss + capital letter Z format, and capital letter Z indicates UTC time. For example, 23:00:10Z represents 23:00:10 UTC.
• When involving date and time, insert an uppercase letter T between them. For example, 2014-06-01T23:00:10Z represents 23:00:10 UTC on June 1, 2014.

Normalized string

A string can usually contain any Unicode character. This flexibility can cause many troubles in programming. Therefore, the concept of “normalized string” is introduced. A normalized string contains only percent-encoded characters and URI (Uniform Resource Identifier) unreserved characters. RFC 3986 stipulates that URI unreserved characters include the following: letters (A-Z, a-z), numbers (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.

BCT product encoding requirements

• Resolvable contents: All request/response body contents are now encoded in UTF-8. Support for additional encoding types will be added in the future.

• Upon request, UrlEncode must be performed for the following items:

  • Object name: The character "/" is ignored for Resource UrlEncode.
  • Query string Value.
  • x-bce-copy-source: The character "/" is ignored.
  • Custom Meta: Meta values only support visible ASCII characters. For characters not supported, it is recommended to use UrlEncode processing.