API Authentication Mechanism

Users can interact with Baidu AI Cloud in two ways, including authentication and anonymity. For the authentication method, the sender identity of a request needs to be verified by using the Access Key Id/Secret Access Key encryption method. Access Key Id (AK) is used to indicate the user. Secret Access Key (SK) is the key used by the user to encrypt the authentication string and by Baidu AI Cloud to verify the authentication string. SK must be kept confidential and only be known by the user and Baidu AI Cloud.

When Baidu AI Cloud receives the user's request, the system will use the same SK and the same authentication mechanism to generate the authentication string and compare it with the authentication string contained in the user's request. If the authentication string is the same, the system considers that the user has the specified operation permission and performs the relevant operation. If the authentication string is different, the system ignores the operation and returns the error code. For details of the authentication mechanism, see Authentication mechanism.

Typesetting Agreement

Time and Date

Date and time can be represented in many ways. For the sake of uniformity, unless it is a convention or an appropriate specification, all the date and time fields specified in the HTTP standard must adopt GMT, and all other date and time fields must adopt UTC and be in accordance with ISO 8601, with the following restrictions::

1. All dates should adopt the form of YYYY-MM-DD, for example, 2016-06-01 is represented as Wednesday, June 1st, 2016.
2. All time should adopt the form of hh:mm:ss, and add a capital Z at the end to indicate UTC time. For example, 23:00:10Z indicates that UTC time is 23:00:10.
3. When combining representations of date and time, add the letter T between the two. For example, 2016-06-01T23:00:10Z indicates that the UTC time is 23:0:10 on Wednesday, June 1, 2016.

General Instructions

API calls follow the HTTP protocol, and each Region adopts a different domain name, and the specific domain name is mongodb.{region}.baidubce.com. The data exchange format is JSON, and all request/response body contents are encoded in UTF-8.

Request Parameters

The request parameters include the following 4 types:

Return Value

The return value has two forms:

API Version Number

Authentication Mechanism

Access Key and request signature are used for all API security authentication. The Access Key consists of an Access Key ID and a Secret Access Key, both of which are strings. For each HTTP request, an authentication string is generated with the algorithm described below. Submit authentication string in Header Fields--Authorization. The server verifies the correctness of the authentication string according to the generation algorithm. The format of the authentication string isbce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}.

• Version is a positive integer.
• Timestamp is the UTC time when the signature is generated
• ExpirationPeriodInSeconds represents the expiration period of the signature.
• SignedHeaders is the list of header fields involved in the signature algorithm Header domains are separated by（;）, such as host ; X-bce-date. The list is in lexicographic order. (API signature only uses host and two headers of x-bce-date)
• Signature is a hexadecimal representation of a 256-bit signature, consisting of 64 lowercase letters.

Definition of Password Encryption and Transmission Specification

All interface parameters involving password need to be encrypted and plaintext transmission is prohibited. All passwords are encrypted by AES 128-bit encryption algorithm, with the first 16 bits of SK as the key. The binary byte stream generated after encryption needs to be converted to hexadecimal and transmitted to the server in the form of string. The specific steps are as follows:

• byte[] bCiphertext= AES(plaintext,SK)
• String strHex = HexStr(bCiphertext)

Idempotent

If the user encounters a request timeout or an internal server error when calling the create interface, the user can try to resend the request, in which case the user avoids creating more resources than expected through the clientToken parameter, guaranteeing the idempotent of the request.

Idempotent is based on clientToken, which is an ASCII string of up to 64 bits in length, usually placed in a query string, such as http://mongodb.bj.baidubce.com/v1/instance?clientToken=be31b98c-5e41-4838-9830-9be700de5a20.

If the user invokes the creation interface with the same clientToken value, the server returns the same request result. So the user can ensure that only one resource is created by providing the same clientToken value during an error retry. If the user provides a used clientToken, but other request parameters (including the queryString and requestBody) are different, and even the url Path is different, it returns the “IdempotentParameterMismatch” error code.

ClientToken is valid for 24 hours, and that the last time the clientToken was received by the server is considered to be standard. That is to say, it the client sends the same clientToken constantly, then this clientTokem will be valid for a long time.

Error Return

Error Return Format

When an error occurs in the request, return detailed error message via response body, following the format below:

Example:

{
    "requestId" : "ae2225f7-1c2e-427a-a1ad-5413b762957d",
    "code"      : "AccessDenied",
    "message"   : "Access denied."
}

Error Return Code

Public Header

Public Request Header

The standard header field of HTTP protocol is no longer listed here. The common header field appears in every Baidu AI Cloud database DocDB for MongoDB API which is required and where the x-bce-content-sha256 header field appears only in POST and PUT requests. POST, PUT, DELETE and other request data are placed in “request body”.

Public Response Header