General Description
API calls utilize the HTTP protocol, and different regions are assigned different domain names. The specific domain name follows the pattern cfs.{region}.baidubce.com. The data exchange format is JSON, and all request and response body contents are encoded in UTF-8. The fsId used in URL parameters serves as the unique identifier for the file system.
Certification
Users who use CFS APIs need to complete certification. Those who have not passed certification can go to the certification under security certification in the Baidu AI Cloud Official Website Console for certification.
Baidu AI cloud offers two authentication methods: personal authentication, enterprise authentication. You can choose one based on your actual situation.
API authentication mechanism
The Access Key and request signature mechanism are uniformly adopted for all API security authentication. Access Key consists of an Access Key ID and a Secret Access Key, both of which are strings. 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 certification string format is bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}.
- The version is a positive integer.
- The timestamp refers to the UTC time when the signature is created.
- The expirationPeriodInSeconds specifies the duration during which the signature remains valid.
- SignedHeaders includes the list of headers involved in the signature algorithm. The headers are separated by semicolons (e.g., host;x-bce-date) and arranged in lexicographical order. (This API signature involves only the host and x-bce-date headers.)
- The signature is a 256-bit signature represented as a 64-character lowercase hexadecimal digest.
When Baidu AI Cloud receives a user's request, the system uses the same SK and certification mechanism to generate a certification string. This string is then compared with the one included in the user's request. If the two match, the system confirms the user has the required permissions and proceeds with the operation. If they differ, the system cancels the operation and returns an error code.
For detailed information on the authentication mechanism, please refer to [Authentication Mechanism](Reference/Authentication mechanism/Introduction.md).
Communication protocol
The CFS API supports both HTTP and HTTPS methods. For improved data security, using HTTPS is strongly recommended.
Request structure description
Component in the request structure is described as follow:
| Parameter type | Description |
|---|---|
| URI | Generally, it is used to specify the operation entity, e.g., PUT /v1/cfs/{fsId} |
| Query String | Request parameters carried in the URL |
| Header | It is passed in through HTTP header fields, such as: x-bce-date |
| Request Body | 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. |
| Response Body | Response data body organized in JSON format. |
Common request headers
The table below shows the common headers used by all CFS APIs. Standard HTTP header fields are not included here.
| Header | Required or not | Description |
|---|---|---|
| Authorization | Yes | Signature string. Refer to Authentication Mechanism for specific string generation method |
| Content-Type | Yes | application/json; charset=utf-8 |
| x-bce-date | Optional | Signature date |
Common response headers
The table below shows the public response headers used by all CFS 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 |
Idempotence
When calling certain APIs, if a timeout or internal server error occurs, users can attempt to resend the request. In such cases, the clientToken parameter ensures no more resources than expected are created, maintaining 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 the same clientToken value is used when calling the creation API, the server will return the same result. If a retry is necessary due to an error, supplying the same clientToken ensures that only one resource is created. If the clientToken has been used previously but other parameters like queryString, requestBody, or even the URL Path differ, an error code of IdempotentParameterMismatch will be issued.
The clientToken remains valid for 24 hours from the last time it was received by the server. In cases where the same clientToken is continuously sent, it will stay valid indefinitely within that time window.
Date and time regulations
There are multiple ways to represent date and time. For uniformity, unless it is conventional or there are corresponding specifications, UTC time shall be used wherever date and time need to be expressed, 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.