Interface Specifications
The data exchange format is JSON, and all request/response body contents are encoded in UTF-8.
Description: As all modifications such as creation and deletion require time for processing at the backend, modifications are designed as asynchronous requests. As long as the parameters are valid, the backend will directly respond with success, and the BLB instance state will change to updating. BLB instances in the updating state cannot undergo other modifications, but the query is not affected. You can check the instance state by calling DescribeLoadBalancers. When the instance state updates to available, you may proceed with subsequent modifications.
Request parameters
Request parameters include the following 4 types:
| Parameter type | Description |
|---|---|
| URI | Generally, it is used to specify the operation entity, e.g., PUT /v1/blb/{blb_id}. |
| Query String | Request parameters carried in the URL |
| Header | It is passed in through HTTP header, such as: x-bce-date |
| Request Body | Request data body organized in JSON format |
Response value description
Response values are in two forms:
| Response content | Note |
|---|---|
| HTTP Status Code | Such as 200, 400, 403, 404, etc. |
| Response Body | Response data body organized in JSON format. |
Common request headers
The following table lists common headers included in all BLB APIs. Standard HTTP header fields are not listed here.
| Header | Type | Required or not | Description |
|---|---|---|---|
| Authorization | String | Yes | Signature string. Refer to [Authentication](Reference/Authentication mechanism/Introduction.md) for specific string generation method. |
| Content-Type | String | Yes | application/json; charset=utf-8 |
| x-bce-date | String | No | Signature date |
Common response headers
The table below displays the public response headers for all BLB APIs. Standard HTTP response headers are not included here.
| Header | Description |
|---|---|
| Content-Type | application/json; charset=utf-8 |
| x-bce-request-id | Request ID of this request |
Date and time
Dates and times can be expressed in various ways. For consistency, all date and time fields specified in the HTTP standard adhere to GMT unless otherwise stated. Other date and time formats consistently follow UTC time based on 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.
Idempotence
During API calls, network issues can often cause clients to lose connection before receiving a response. In such cases, the client cannot ascertain whether the server has processed the request. Retrying may lead to issues; for instance, resending a Create instance request could result in duplicate instances being created. To resolve this, idempotence mechanisms should be employed.
Idempotence ensures that sending the same request multiple times results in the same outcome as sending it just once.
The BCE API employs the clientToken mechanism to guarantee the idempotence of API requests.
clientToken
clientToken is an ASCII string with a length not exceeding 64 bits, usually placed in the query string, such as http://rds.bj.baidubce.com/v1/instance?clientToken=be31b98c-5e41-4838-9830-9be700de5a20.
The uniqueness of a clientToken is tied to the specific service and user. Since clientTokens from different users are independent, users need not worry about potential conflicts with others. For APIs that allow anonymous calls, all anonymous users are treated as a single user. It is the responsibility of anonymous users to ensure their clientTokens are unique by generating long, random tokens to minimize conflict risks. Additionally, clientTokens from one service are independent of those from another. Furthermore, for services that are not globally unique, clientTokens can be reused across different regions.
A clientToken remains valid for at least 24 hours, starting from the most recent time the server received it. Therefore, as long as the client continues to send the same clientToken, its validity will be extended indefinitely.
Server logic
When a server receives a request containing a clientToken, it first checks whether this clientToken was previously sent by the calling user. If it was, the server verifies whether all API parameters are fully identical. If there are discrepancies, it responds with IdempotentParameterMismatch. If they are consistent, the server provides normal results.
For example, when creating an instance, the server typically responds with the instance's state. If the clientToken is the same, instance creation will not be repeated, and the current state of the corresponding instance will be returned directly.
API parameters here specifically include aspects that influence the result, such as URL, query string, and headers. Certain elements, like Authorization, which do not affect the result, are excluded.
Result pagination
List APIs usually require pagination for their queries. If an API returns a large number of results, it limits the response count and enables the complete retrieval of results through pagination. In such cases, the DescribeTCPListeners API uses a uniform marker mechanism for pagination.
- maxKeys: Specifies the maximum number of query results to return per page.
- marker: A marker in the query request used to indicate the starting position for the query. The first query request does not require a marker to be set. If a page does not list all results, set the nextMarker provided by the server as the marker for the subsequent query.
- isTruncated: A value of true indicates there is more data to follow, while false means this is the final page.
- nextMarker: Provides the marker value required to retrieve the next page. This field will not appear if isTruncated is set to false.