General Description
API calls adhere to the HTTP protocol, with different regions using different domain names. The specific domain name is bcm.{region}.baidubce.com. The data exchange format is JSON, and all request and response body content is encoded in UTF-8.
API authentication mechanism
The Access Key and request signature mechanism are uniformly adopted for all API security authentication. An Access Key consists of an Access Key ID and a Secret Access Key, both of which are strings (for methods of retrieving AK/SK, refer to [Retrieve AK/SK](Reference/Retrieve AK and SK/How to Obtain AKSK.md)). For each HTTP request, use the algorithm described below to generate a authentication string. Submit the certification string in the Authorization header. The server verifies the correctness of the authentication string based on the generation algorithm. The format of the certification string is
bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}。
• version is a positive integer. • timestamp is the UTC time when the signature is generated. • expirationPeriodInSeconds indicates the validity period of the signature. • signedHeaders is the list of headers involved in the signature algorithm. Separate headers with semicolons (;), such as host; x-bce-date. The list is sorted in lexicographical order. (This API signature only contains two headers of host and x-bce-date) • Signature is a 256-bit signature represented by 64-character lowercase hex digest.
When Baidu AI Cloud receives a user's request, the system uses the same SK and authentication mechanism to generate an authentication string and compares it to the string included in the user's request. If the two strings match, the system confirms the user's permission to perform the operation and executes it. If they do not match, the system skips the operation and returns an error code.
For detailed information on the authentication mechanism, please refer to [Authentication](Reference/Authentication mechanism/Introduction.md).
Communication protocol
The BCM API supports HTTP calls in all regions and HTTPS calls specifically in the Wuhan and Shanghai regions.
Request structure description
The data exchange format is JSON, and all request and response body content is encoded in UTF-8.
Request parameters include the following 4 types:
| Parameter type | Description |
|---|---|
| URL | It is usually used to specify the operation entity, such as: POST /v{version}/instance/{instanceId} |
| Query | Request parameters carried in the URL |
| HEADER | It is passed in through HTTP header fields, such as: x-bce-date |
| RequestBody | Request data body organized in JSON format |
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. |
Date and time regulations
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:
- All dates are expressed in the format of
YYYY-MM-DD. For example, June 1, 2014 is expressed using2014-06-01. - Time shall be expressed in the
hh:mm:ss+ capital letter Z format, and capital letter Z indicates UTC time. For example, 23:00:10Z represents 23:00:10 UTC. - When involving date and time, insert an uppercase letter T between them. For example,
06/01/2014 23:00:10represents 23:00:10 UTC on June 1, 2014.
Normalized string
A string can usually contain any Unicode character. This flexibility can cause many troubles in programming. Therefore, the concept of “normalized string” is introduced. A normalized string contains only percent-encoded characters and URI (Uniform Resource Identifier) unreserved characters. RFC 3986 stipulates that URI unreserved characters include the following: letters (A-Z, a-z), numbers (0-9), hyphens (-), dots (.), underscores (_), tildes (~). The way to convert any string into a normalized string is:
- Convert the string into a UTF-8 encoded byte stream.
- Leave all unreserved URI characters unchanged.
- Perform percent-encoding as specified in RFC 3986 on the remaining bytes, i.e., a % followed by two hexadecimal letters representing the byte value. Letters are in uppercase.
Example:
Original string:
this is an example fortesting, Corresponding normalized string:this%20is%20an%20example%20for%20%E6%B5%8B%E8%AF%95.