The data exchange format is JSON., all request/response body contents are encoded in UTF-8.

Note: For all modification operations such as creation and deletion, the back end requires certain time to process these modification operations, so the modification operation is designed as an asynchronous request. As long as the parameter is valid, the back end will directly return successfully. Meanwhile, the status of BLB instance becomes "updating". The BLB instances in the status of "updating" cannot be modified, and the query operation is not affected. You can call the DescribeLoadBalancers to view the instance status. When the instance status is updated as available, you can continue to send the following modification operations.

Request Parameter

The request parameters include the 4 kinds below:

Return Value Description

There are two types of return values:

Public Request Header

The Table below lists the public headers carried by all BLB APIs. The standard header of the HTTP protocol is not listed here.

Public Response Header

The Table below lists the public response headers of all BLB APIs. The standard response header of the HTTP protocol is not listed here.

Date and Time

There are various methods to express date and time. For the purpose of unification, unless there are conventions or corresponding specifications, all fields expressing date and time specified in the HTTP standard utilize GMT, and UTC time for other places expressing date and time. The users should follow ISO 8601, and the following restrictions are made:

• Fields expressing the date all utilize the YYYY-MM-DD format, e.g.2014-06-01 which means June 1, 2014.
• Fields expressing time all utilize the hh:mm:ss format, with the capital letter Z added at the end, which means UTC time. E.g. 23:00:10Z means UTC time: 23:00:10.
• When the date and time is combined, the capital letter T is added between the two items, e.g. 2014-06-01T23:00:10z means UTC time: 23:00:10 on June 1, 2014.

Idempotency

When the API is called, the problems in network and other aspects can easily cause the connection disrupted when the client doesn't receive the response. At this time, the client cannot confirm whether the server receives request, and the retry may cause problems. For example, a request for creating an instance may cause repeated creation when it is sent for multiple times. For this, the idempotency mechanism should be added for response.

The idempotency means that no matter how many times one and the same request is sent, the result is the same as when it is sent once.

The BCE API uses the clientToken mechanism to guarantee the idempotence of API calling.

ClientToken

The clientToken is a ASCII string with a length not exceeding 64 bits and generally put in the query string, e.g. http://rds.bj.baidubce.com/v1/instance?clientToken=be31b98c-5e41-4838-9830-9be700de5a20

The uniqueness of clientToken is related with services and users. The clientTokens of different users are unrelated to each other, so the users don't necessarily pay attention to the clientToken conflicts with other users. For APIs that allow anonymous calls, all anonymous users are considered as the same user. While ensuring the uniqueness of clientToken, anonymous users shall reduce the collision probability to be low enough by randomly generating long tokens. clientTokens of different services are uncorrelated to each other. Meanwhile, clientTokens may be reused for different regions of a non-global unique service.

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.

Server Logic

When the server receives a request with clientToken, it should first check whether the user initiating the call has ever sent the same clientToken. If so, it shall check whether API parameters are fully consistent. If not, it shall return IdempotentParameterMismatch. If API parameters are fully consistent, it shall return normal results.

For example, it usually returns instant state in case of the creation of an instance. In case the clientTokens are the same, instead of the repeated creation of instances, it will return the current state of the corresponding instance directly.

API parameters here refer in particular to urls, query strings, and headers which may have impacts on the results. Some parts that do not have impacts on the results (such as Authorization) are not included.

Result Paging

The query list interface usually needs to be paged. The number of returned results shall be limited in case API returns too many results. Paging mechanism shall be used for obtain the full list. DescribeTCPListeners interface. marker mechanism is used for all pages.

• maxKeys: The maximum number of query results per page.
• marker: The query flag, which is set in the query request, is used to mark the starting query position. There is no need to set marker for the first query request. In case it is not fully listed in one page, nextMarker returned by the server shall be set as the marker for the next query.
• isTruncated: True means there are additional data in the following pages and false means the current page is the last page.
• nextMarker: The marker value requiring to be passed in order to acquire the next page. The domain doesn't appear when isTruncated is false.