General Description
An API should be called in accordance with the HTTP protocol, and each region should use a different domain name, which should be dcc.{region}.baidubce.com
. The data exchange format adopts JSON, and all request/response body
contents are encoded in UTF-8.
Request Parameters
The request parameters are divided into the following 4 types:
Parameter Type | Description |
---|---|
URI | It is usually used to indicate the operating entity, such as PUT /v1/eip/{eip}. |
Query parameter | The request parameter carried in the URL |
HEADER | The parameter which is passed in via the HTTP header field, such as x-bce-date. |
RequestBody | The request data body organized in the JSON format |
Return Value Description
The return values have two forms:
Return Contents | Description |
---|---|
HTTP STATUS CODE | E.g. 200, 400, 403, 404, etc. |
ResponseBody | The response data body organized in the JSON format |
API Version Number
Parameter | Type | Parameter Position | Description | Required |
---|---|---|---|---|
version | String | URI parameter | API version number (the current API version number is v1.) | Yes |
Certification System
The Access Key and request signature system is used for all API security certification. The Access Key consists of an Access Key ID and a Secret Access Key, both of which are strings. For each HTTP request, a certification string needs to be generated with the algorithm described below. You need to submit a certification string which is placed in the Authorization header field. After that, the server is going to verify whether the certification string is correct or not according to the generation algorithm. The format of the certification string is bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}
.
- The version number is a positive integer.
- The timestamp refers to the UTC time when the signature is generated
- expirationPeriodInSeconds indicates the period of validity of the signature.
- signedHeaders refers to the list of header fields involved in the signature algorithm. The header domain names are separated by semicolons (;), such as host; X-bce-date. The list is sorted in alphabetical order. (This API signature only uses two headers, that is, host and x-bce-date.)
- The signature, which is a 256-bit signature represented in the hexadecimal numeral system, consists of 64 lowercase English letters.
For more information on the authentication and certification system, please see Authentication Mechanism.
Definition of the Password Encryption and Transmission Specification
All interface parameters involving passwords need to be encrypted and plaintext transmission is prohibited. All passwords need to be encrypted with the AES 128-bit encryption algorithm, and the first 16 bits of SK serve as the key. The binary byte stream generated after encryption needs to be converted to a hexadecimal number, and then transmitted to the server in the form of a string. The specific steps are as follows:
byte\[] bCiphertext= AES(plaintext,SK)
String strHex = HexStr(bCiphertext)
Idempotence
If a request timeout or an internal server error occurs when a created interface is called, the user may try to resend the request. At this point, the system prevents more resources than expected from being created with the clientToken parameter, to guarantee the idempotence of the request.
The idempotency is based on clientToken, which is an ASCII string with the length of up to 64 bits and usually placed in a query string, such as http://dcc.bj.baidubce.com/v1/dedicatedHost?clientToken=be31b98c-5e41-4838-9830-9be700de5a20
.
If a created interface is called with the same clientToken value, the server is going to return the same request result. Therefore, if the user has another try when an error occurs, it can provide the same clientToken value to ensure that only one resource is created. If it provides a used clientToken with different other request parameters (including queryString and requestBody) and different URL Path, the error code IdempotentParameterMismatch
is going to be returned.
The period of validity of clientToken is 24 hours starting from the time when the server receives this clientToken for the last time. That is to say, if the client sends the same clientToken continuously, this clientTokem is going to remain valid for a long time.