The API calling conforms to the HTTP protocol, and the domain name is bcc.bj.baidubce.com. The data exchange format is JSON, and all contents of request/response body are encoded in UTF-8.

Real Name Authentication

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 "Real Name Authentication" under the security authentication in the Baidu AI Cloud Official Website Console for the authentication. Baidu Cloud provides two authentication methods: Personal Authentication and Enterprise Authentication. You can choose one for authentication according to the actual situation.

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 using the algorithm described below. The authentication string submitted is put into the Authorization Header Field. The server verifies the correctness of the authentication string based on the generation algorithm. The format of the authentication string isbce-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; Xbcedate. The list is in lexicographic order. (API signature only uses two headers of host and x-bce-date)
• The signature is a 256-bit signature in hexadecimal representation, consisting of 64 lowercase letters. When Baidu AI Cloud receives the user's request, the system uses the same SK and the same authentication mechanism to generate the authentication string. Then, the system compares the authentication string with that 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 more information on the authentication mechanism, see Authentication Mechanism.

Communication Protocol

HTTP and HTTPS are both supported. 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 operating entity, such as POST /v{version}/instance/{instanceId} | | Query Parameter | Request parameter contained in the URL, which is usually used to indicate the action to be taken on the entity | | HEADER | Parameter passed in via the HTTP header field, such as x-bce-date | | RequestBody | Request data body organized in the JSON format |

Response Structure Description

The response value includes two forms:

API Version Number

Idempotence

If the user encounters a request timeout or an internal server error when calling the interface used to create the resource, the user may try to resend the request. Thus, it may cause the creation of excessive resources. In this case, the user can use the clientToken parameter to avoid creating more resources than expected, that is to say, guarantee the idempotence 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.

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:

• All dates should adopt the form ofYYYY-MM-DD, for example,2014-06-01is represented as 1 June, 2014.
• All time should adopt the form ofhh:mm:ssand add a capital Z at the end to indicate UTC time. For example,23:00:10Zindicates that UTC time is 23:0:10
• As to the combination of date and time, add the letter T between the two. For example2014-06-01T23:00:10Zindicate UTC time is 23:0:10 on 1 June, 2014.

Normalized String

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 the string to the byte string coded by UTF-8.
• Leave all URI non-reserved characters as the same.
• Perform Percent-Encoding on the rest of the bytes according to RFC 3986, that means a % is followed by two hexadecimal letters representing the byte value. All letters are capitalized. 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