General Description
Call methods
API calls comply with HTTP/HTTPS protocols, with different domain names used for each region. For instance, the specific domain name for North China - Beijing is http(s)://bls-log.bj.baidubce.com. The data exchange format is JSON, and all request and response body content is encoded in UTF-8.
API authentication mechanism
All APIs complete request signing through AK (Access Key ID)/SK (Secret Access Key) to pass server authentication and authorization. For detailed information on the authentication mechanism, please refer to Authentication Mechanism.
Request structure description
| Parameter type | Description |
|---|---|
| HTTP Method | The HTTP request method indicates the type of operation you are requesting from the server. |
| HEADER | It is passed in through HTTP header fields, such as: x-bce-date |
| URI | It is usually used to specify the operation entity, such as: POST /v{version}/instance/{instanceId} |
| Query | Request parameters carried in the URL |
| RequestBody | Request data body organized in JSON format |
The data exchange format is JSON, and all request and response body content is encoded in UTF-8.
Response structure description
Response values are in two forms:
| Response content | Description |
|---|---|
| HTTP STATUS CODE | Such as 200, 400, 403, 404, etc. |
| ResponseBody | Response data body organized in JSON format. |
Common request headers
BLS APIs adopt a Restful style, and public request headers apply to all API requests, with specific definitions as follows:
| Header | Types | Description |
|---|---|---|
| Authorization | String | Certification information for verifying the validity of the request. For more details, see Authentication |
| Host | String | Access Host value, e.g., bls-log.{region}.baidubce.com |
| Content-Type | String | HTTP request content type as defined in RFC 2616; currently, BLS API requests only support application/json |
| Content-Length | Int | HTTP request content length as defined in RFC 2616 |
| X-Bce-Date | String | A string representing the date. |
| X-Bce-Request-Id | String | request id of this request |
| X-Bce-Security-Token | String | Required when sending data using STS temporary identity; do not fill in other cases |
| X-Region | String | Region requested for access |
As an example, the following is the content of a standard request header for user querying log set details:
1GET /v1/logstore/demo HTTP/1.1
2X-Bce-Date: 2019-09-04T13:04:26Z
3Host: bls-log.bj.baidubce.com
4Content-Type: application/json
5Authorization:bce-auth-v1/18717522d39411e9b721df098b0b908c/2019-09-10T07:00:20Z/1800/content-type;host;x-bce-date;x-bce-request-id/6a7cb6c9ac7ec156c805e55e7d0bcfc443b47feee97cf099c1c0d9Common response headers
BLS APIs adopt a Restful style, and public response headers apply to all API requests, with specific definitions as follows:
| Header | Types | Description |
|---|---|---|
| Content-Type | String | HTTP response content type as defined in RFC 2616; currently, BLS API requests only support application/json |
| Content-Length | Int | HTTP request content length as defined in RFC 2616 |
| x-Bce-Request-Id | String | The request ID returned by the server is used to track and locate issues. Users can provide this ID when submitting tickets. |
Idempotence
When calling the resource creation API, if a request timeout or internal server error occurs, the user may attempt to resend the request, resulting in excessive creation of resources. In this case, the user can apply the clientToken parameter to prevent the creation of more resources than expected, thereby guaranteeing the idempotence of the request. Idempotence is based on clientToken, which is an ASCII string with a length not exceeding 64 bits, usually placed in the query string, such as http://bcc.bj.baidubce.com/v1/instance?clientToken=be31b98c-5e41-4838-9830-9be700de5a20. If a user calls the creation API with the same clientToken value, the server will return the same request result. Therefore, when a user retries after encountering an error, they can ensure that only one resource is created by providing the same clientToken value; if a user provides a previously used clientToken, but other request parameters (including queryString and requestBody) are different or even the URL Path is different, an error code of IdempotentParameterMismatch will be returned. The validity period of clientToken is 24 hours, based on the last time the server received the clientToken. That is to say, if the client continuously sends the same clientToken, the clientToken will be valid for a long time.
Date and time regulations
Dates and times can be expressed in many ways. For uniformity, unless otherwise conventional or specified, UTC time is used wherever dates and times are required, following ISO 8601, with the following constraints:
- Dates should be formatted as YYYY-MM-DD. For instance, 2014-06-01 corresponds to June 1, 2014.
- Time should be written in the hh:mm:ss format followed by an uppercase letter Z, which denotes UTC time. For example, 23:00:10Z equates to 23:00:10 UTC.
- When combining date and time, use a capital letter T to separate them. For example, 2014-06-01T23:00:10Z signifies 23:00:10 UTC on June 1, 2014.