General Description
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, currently set to 1.
- 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.
For detailed information on the authentication mechanism, please refer to Authentication.
Communication protocol
Both HTTP and HTTPS methods are supported. For better data security, it is recommended to use HTTPS.
Request structure description
Request parameters include the following 4 types:
| Parameter type | Description |
|---|---|
| URI | Generally, it is used to specify the operation entity, e.g., GET /v1/csn |
| Query | Request parameters carried in the URL |
| 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 | Note |
|---|---|
| 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 | URL parameter | The current API version is v1. | 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.