接口规范

数据交换格式为JSON，所有request/response body内容均采用UTF-8编码。

说明： 所有创建删除等修改操作，后端需要一定时间处理，所以修改类操作设计为异步请求。只要参数合法，后端会直接返回成功，同时BLB实例的状态会变成updating，处于updating状态的BLB实例不能进行其他修改操作，查询操作不受影响。您可以通过调用DescribeLoadBalancers查看实例状态，当实例状态更新为available时可以继续发送后续修改操作。

请求参数

请求参数包括如下4种：

参数类型	说明
URI	通常用于指明操作实体，如:PUT /v1/blb/{blb_id}
Query String	URL中携带的请求参数
Header	通过HTTP头域传入，如x-bce-date
Request Body	通过JSON格式组织的请求数据体

返回值说明

返回值分为两种形式：

返回内容	说明
HTTP Status Code	如200,400,403,404等
Response Body	JSON格式组织的响应数据体

公共请求头

下表列出了所有BLB API所携带的公共头域。HTTP协议的标准头域不在此处列出

头域（HEADER）	类型	是否必须	说明
Authorization	String	是	签名字符串，生成签名字符串的方法请参考鉴权认证
Content-Type	String	是	application/json; charset=utf-8
x-bce-date	String	否	签名日期

公共响应头

下表列出了所有BLB API的公共响应头域。HTTP协议的标准响应头域不在此处列出

头域（HEADER）	说明
Content-Type	application/json; charset=utf-8
x-bce-request-id	本次请求的requestId

日期与时间

日期与时间的表示有多种方式。为统一起见，除非是约定俗成或者有相应规范的，凡是HTTP标准中规定的表示日期和时间字段用GMT，其他日期时间表示的地方一律采用UTC时间，遵循ISO 8601，并做以下约束：

• 表示日期一律采用YYYY-MM-DD方式，例如2014-06-01表示2014年6月1日。
• 表示时间一律采用hh:mm:ss方式，并在最后加一个大写字母Z表示UTC时间。例如23:00:10Z表示UTC时间23点0分10秒。
• 凡涉及日期和时间合并表示时，在两者中间加大写字母T，例如2014-06-01T23:00:10Z表示UTC时间2014年6月1日23点0分10秒。

幂等性

在调用API时，很容易出现由于网络等问题导致客户端没收到响应连接就中断的情况。此时客户端无法得知服务器端是否收到了请求，重试又可能导致问题。例如一个创建实例的请求被多次发送就可能出现重复创建。对此，应加入幂等性的机制来加以应对。

幂等性的意思是无论同一个请求被重复发送多次，其结果都和发送一次一样。

BCE API采用clientToken机制来保证API调用的幂等性。

clientToken

clientToken是一个长度不超过64位的ASCII字符串，通常放在query string里面，如http://rds.bj.baidubce.com/v1/instance?clientToken=be31b98c-5e41-4838-9830-9be700de5a20。

clientToken的唯一性与服务及用户相关。不同用户的clientToken互不相关，因此用户无需关注和其他用户的clientToken冲突问题。对于允许匿名调用的API，所有匿名用户视为同一个用户。匿名用户要保证clientToken的唯一性时，应采用随机生成长token的方式，将冲突概率降到足够小。不同服务的clientToken也互不相关。同时一个非全局唯一的服务的不同region之间也可以重复使用clientToken。

clientToken的有效期为至少24小时，以服务端最后一次收到该clientToken为准。也就是说，如果客户端不断发送同一个clientToken，那么该clientToken将长期有效。

服务端逻辑

当服务端收到带有clientToken的请求时，首先检查发起调用的用户是否曾经发送过同一个clientToken。如是，则应检查API的参数是否完全一致。当不一致时，返回IdempotentParameterMismatch。如完全一致，应返回正常结果。

例如创建一个实例时，通常会返回实例状态。如果clientToken相同，则不再重复创建实例，直接返回对应实例当前状态。

这里的API参数特指会对结果产生影响的url、query string和header等。某些不产生影响的部分如Authorization不包含在内。

结果分页

查询列表类接口通常会有分页需求。当API返回结果过多时，应限制返回数量，采用分页机制来获取全列表。DescribeTCPListeners接口。所有分页统一采用marker机制。

• maxKeys：每页所包含查询结果的最大数量。
• marker：查询请求里设置的查询标志位，用来标记查询的起始位置。第一次查询请求时无需设置marker，如果发现一页没列举完，再把服务端返回的nextMarker设为下次查询的marker。
• isTruncated：true表示后面还有数据，false表示已经是最后一页。
• nextMarker：获取下一页所需要传递的marker值。当isTruncated为false时，该域不出现。