General Description
API calls follow the HTTP protocol, and each Region adopts a different domain name, and the specific domain name is eip.{region}.baidubce.com. The data exchange format is JSON, and all request/response body contents are encoded in UTF-8.The eip used in URL parameters is expressed with dotted decimal notation.
Request parameter
The request parameters include the 4 kinds below:
| Parameter type | Description |
|---|---|
| URI | is generally used to indicate the operation entity, e.g. PUT /v1/eip/{eip} |
| Query parameter | request parameters carried in URL |
| HEADER | is introduced via HTTP header, e.g.: x-bce-date |
| RequestBody | Request data body organized in JSON format |
| Parameter type | Description |
|---|---|
| URI | Generally used to indicate the operation entity, e.g. PUT / v1/ eip/{ eip}. |
| Query parameter | Request parameters carried in URL. |
| HEADER | Passed by the HTTP header, e.g. x-bce-date. |
| RequestBody | Request data body organized in JSON format. |
Return value description
There are two types of return values:
| Return contents | Description |
|---|---|
| HTTP STATUS CODE | e.g. 200,400,403,404, etc. |
| ResponseBody | Response data body organized in JSON format |
| Return Content | Description |
|---|---|
| HTTP STATUS CODE | E.g. 200,400,403,404, etc. |
| ResponseBody | Response data body organized in JSON format. |
API Version Number
| Parameter | Type | Parameter position | Description | Required or not |
|---|---|---|---|---|
| version | String | URL parameter | API version number, current API version v1. | Yes |
Authentication Mechanism
The security authentication of all APIs utilizes the Access Key and request signature mechanism. Access Key consists of Access Key ID and Secret Access Key, both of which are strings. For each HTTP request, the algorithm described below is utilized to generate one authentication string. The authentication string is submitted in the Authorization header. The server verifies the correctness of authentication string based on the generating algorithm. The format of the authentication string is bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}.
- version is a positive integer with value of 1 currently.
- The timestamp stands for the UTC time when the signature is generated.
- The expirationPeriodInSeconds stands for the expiration period of signature.
- The signedHeaders stands for the header list involved in the signature algorithm. The headers are separated by a semicolon (;), e.g. host; x-bce-date. The list is arranged in lexicographic order. (This API signature only utilizes two headers of host and x-bce-date.)
- The signature is the 256-bit signed sexadecimal notation, and composed of 64 lower-case letters.
For the detailed contents of authentication certification mechanism, please see Authentication Certification.
Idempotency
If a request timeout or internal server error occurs when the create interface is called, the user may try to resend the request. At this time, the user can avoid creating more resources than expected through the clientToken parameter, that is, to ensure the idempotence of the request.
Idempotency is based on clientToken, an ASCII string no longer than 64 bits usually placed in a query string such as http://eip.bj.baidubce.com/v1/instance? clientToken=be31b98c-5e41-4838-9830-9be700de5a20.
If the user calls the creation interface with the same clientToken value, the server will return the same request result. Therefore, when the user encounters an error and retries, he can provide the same clientToken value to ensure that only one resource is created. If the user provides a used clientToken, but other request parameters (including queryString and requestBody) are different or even URL path is different, the error code of IdempotentParameterMismatch will be returned.
The clientToken is valid for 24 hours, subject to the last time when the server receives the clientToken. That is, if the client continuously sends the same clientToken, the clientToken will be valid for a long time.