General Description
API calls use the HTTP protocol, and the domain name is 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 dedicated line APIs need to complete certification. Those who have not passed certification can go to the certification under security certification in the Baidu AI Cloud Official Website Console for certification. Baidu AI cloud offers two certification methods: personal certification , enterprise certification . You can choose one based on your actual situation.
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.)
- Signature is a 256-bit signature represented by 64-character lowercase hex digest. When Baidu AI Cloud receives a user's request, the system will use the same SK and identical certification mechanism to generate a certification string, and then compare it with the certification string included in the user's request. If the authentication strings are the same, the system considers that the user possess the specified operation permission and proceeds with the relevant executions. If the authentication strings differ, the system will skip this 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:
| Parameter type | Description |
|---|---|
| URI | It is usually used to specify the operation entity, such as: POST /v{version}/instance/{instanceId} |
| Query | Request parameters included in the URL, typically specifying the action to be performed on an entity |
| HEADER | It is passed in through HTTP header, 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. |
Common request header and common response header
Common request headers
| Common header | Description |
|---|---|
| Authorization | Include both the Access Key and the request signature. |
| Content-Type | application/json; charset=utf-8。 |
| x-bce-date | A string representing the date that complies with API specifications. |
Standard HTTP protocol header fields are not included in this list. Key header fields are required for all network diagnosis APIs. For POST, PUT, DELETE, and similar requests, data should be placed in the request body.
Common response headers
| Common header | Description |
|---|---|
| Content-Type | application/json; charset=utf-8。 |
| x-bce-request-id | These headers are generated by the VPC backend and automatically included in the response header. |
API version number
| Parameters | Types | Parameter location | Description | Required or not |
|---|---|---|---|---|
| version | String | URI parameter | API version number, current value is 2 | Required |
Idempotence
When calling the resource creation API, if a request timeout or internal server error occurs, the user may attempt to resend the request, resulting in excessive creation of resources. In this case, the user can apply the clientToken parameter to prevent the creation of more resources than expected, thereby guaranteeing the idempotence of the request.
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 a user calls the creation API with the same clientToken value, the server will return the same request result. Therefore, when a user retries after encountering an error, they can ensure that only one resource is created by providing the same clientToken value; if a user provides a previously used clientToken, but other request parameters (including queryString and requestBody) are different or even the URL Path is different, an error code of IdempotentParameterMismatch will be returned.
The validity period of clientToken is 24 hours, based on the last time the server received the clientToken. That is to say, if the client continuously sends the same clientToken, the clientToken will be valid for a long time.
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-01represents 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:10Zrepresents 23:00:10 UTC. - When involving date and time, insert an uppercase letter T between them. For example,
2014-06-01T23:00:10Zrepresents 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 specified in RFC 3986 on the remaining bytes, i.e., a % followed by two hexadecimal letters representing the byte value. Letters are in uppercase.
Example:
Original string:
this is an example for testing, Corresponding normalized string:this%20is%20an%20example%20for%20%E6%B5%8B%E8%AF%95.