API calls follow the HTTP protocol, and each Region adopts a different domain name, and the specific domain name is cfs.{region}.agilecloud.com. The data exchange format is JSON, and all request/response body contents are encoded in UTF-8.The fsId used in the URL parameter is the unique resource identifier of the file system.

Note: 1.Before using the API interface, please enter the "Identity Verification" page for "Enterprise Authentication" or "Personal Authentication" according to the actual situation of the user. For detailed operation steps, please see "Identity Verification".
2.For region information, please see Service Domain Name.

API Authentication Mechanism

The security authentication of all API utilizes the Access Key and request signature mechanism. Access Key consists of Access Key ID and Secret Key, both of which are strings. For each HTTP request, the algorithm described below is utilized to generate one authentication string. The authentication string is submitted in the Authorization header. The server verifies the correctness of authentication string based on the generating algorithm. The format of the authentication string is bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}.

• The version stands for a positive integer.
• The timestamp stands for the UTC time when the signature is generated.
• The expirationPeriodInSeconds stands for the expiration period of signature.
• The signedHeaders stands for the header list involved in the signature algorithm. The headers are separated by a semicolon (;), e.g. host; x-bce-date. The list is arranged in lexicographic order. (This API signature only utilizes two headers of host and x-bce-date.)
• The signature is the 256-bit signed sexadecimal notation, and composed of 64 lower-case letters.

After cloud platform receives a request of users, the system will use the same SK and authentication mechanism to generate an authentication string, and compare it with the authentication string contained in the user request. If the two authentication strings are the same, the system considers that the user has the designated operation permission, and executes the related operations; if the two authentication strings are different, the system will ignore the operation and return an error code.

For details of authentication mechanism, please see Authentication Mechanism.

Idempotency

Users may try to resend a request if they encounter a request timeout or an internal server error when calling an interface. At this time, users can avoid creating more resources than expected by using the clientToken parameter to ensure the idempotency of the request.

Idempotency is based on clientToken, an ASCII string no longer than 64 bits usually placed in a query string such as http://bcc.bj.agilecloud.com/v1/instance? clientToken=be31b98c-5e41-4838-9830-9be700de5a20.

If the user calls the creation interface with the same clientToken value, the server will return the same request result. Therefore, when the user encounters an error and retries, he can provide the same clientToken value to ensure that only one resource is created. If the user provides a used clientToken, but other request parameters (including queryString and requestBody) are different or even URL path is different, the error code of IdempotentParameterMismatch will be returned.

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.

Date and Time Specification

There are various methods to express date and time. For the sake of uniformity, unless it is a convention or a corresponding specification, wherever the date and time is required, UTC time shall be used, ISO 8601 shall be followed , and the following constraints shall be met:

1.Fields expressing the date all utilize the YYYY-MM-DD format, e.g.2014-06-01 which means June 1, 2014. 2.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. 3.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.

Request Parameter

The request parameters include the 4 kinds below:

Return Value Description

There are two types of return values:

Public Request Header

The following table lists the common headers carried by all CFS API. The standard header of the HTTP protocol is not listed here.

Public Response Header

The following table lists the common response headers for all CFS API. The standard response header of the HTTP protocol is not listed here.

Error Code

The detailed error information is returned through Response Body in case of a request error, and the following format is followed:

Example

{
    "requestId" : "ae2225f7-1c2e-427a-a1ad-5413b762957d",
    "code" : "NoSuchKey",
    "message" : "The resource you requested does not exist"
}

BCE Common Error Code

The following table lists the common error codes for all API. Each service should customize the error code on this basis.

CFS Service Error Code