API is called in accordance with HTTP protocol, each region should use a different domain name, and the specific domain name is “drds.{region}.baidubce.com”. The data exchange format is JSON, and all request/response body contents are UTF-8 encoded.

Identity verification

The Identity Verification is required for users who use DRDS API. Users who fail to pass the Identity Verification can go to the "Identity Verification" under the security authentication in the Baidu AI Cloud Official Website Console for the authentication. Baidu Cloud provides two authentication methods: Personal Authentication and [Enterprise Authentication](UserGuide/Identity Verification/Personal Authentication.md). You can choose one for authentication according to the actual situation.

API authentication mechanism

Access Key and request signature mechanism are used for security authentication of all APIs. The Access Key consists of Access Key ID and Secret Access Key, both of which are strings. For each HTTP request, use the algorithm described below to generate an authentication string. The submitted authentication string is placed in the Authorization header field. The server verifies the correctness of the authentication string according to the generation algorithm. The format of the authentication 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 period of validity of the signature.
• SignedHeaders is a list of header fields involved in the signature algorithm. A semicolon (;) is used to separate header domain names, e.g., host;x-bce-date. The list is arranged in the lexicographical order. (This API signature uses the host and x-bce-date headers only)
• The signature is a hexadecimal representation of a 256-bit signature, and consists of 64 lowercase letters.

When Baidu AI Cloud receives the user's request, the system uses the same SK and the same authentication mechanism to generate the authentication string. Then, the system compares the authentication string with that contained in the user's request. If both authentication strings are the same, the system deems that the user has the specified operation privilege, so the system performs relevant operations. If both authentication strings are different, the system ignores this operation and return an error code.

For the detailed content of the authentication mechanism, see the Authentication Mechanism.

Communication protocol

The system supports HTTP and HTTPS calling methods. To improve the data security, we recommend to use the HTTPS calling method.

Description of the request structure

The data exchange format is JSON, and all request/response body contents are UTF-8 encoded.

The request parameters include the following 4 types:

Description of the response structure

The response value has two forms:

API version number

Idempotence

If the user encounters a request timeout or an internal server error when calling the interface used to create the resource, the user may try to resend the request. Thus, it may cause the creation of excessive resources. In this case, the user can use the clientToken parameter to avoid creating more resources than expected, that is to say, guarantee the idempotence of the request.

The idempotence is based on the clientToken. The clientToken is an ASCII string with a length of not exceeding 64 bits and is usually placed in a query string, e.g., https://drds.bj.baidubce.com/v1/instance?clientToken=be31b98c-5e41-4838-9830-9be700de5a20.

If the user uses the same clientToken value to call the creation interface, the server returns the same request result. Therefore, after encountering an error and retrying to send the request, the user can provide the same clientToken value to ensure that only one resource. If the user provides a used clientToken value, but uses other different request parameters (including queryString and requestBody) or even a different url Path, the system returns the error code “IdempotentParameterMismatch”.

The period of validity of the clientToken is 24 hours and starts from the time when the server receives the clientToken the last time. That is to say, if the client sends the same clientToken constantly, the clientToken is valid for a long time.

Date and time specification

The date and time can be expressed in many ways. For unification, unless it is established by convention or has corresponding specifications, UTC time shall be adopted everywhere where date and time are required, ISO 8601 shall be followed, and the following restrictions shall be made:

• The date is represented in the format of YYYY-MM-DD, for example, 2014-06-01represents June 1, 2014.
• hh:mm:ss mode must be adopted for time representation, and a capital letter Z is attached for representation of UTC time. For example, 23:00:10Z represents 23:00:10 UTC.
• Where the date and time are indicated at the same time, add the letter T between the two parts, for example.2014-06-01T23:00:10Z represents that the UTC time is 23:0:10 on Sunday, June 1, 2014.

Service domain name

Common request header and common response header

Common request header

Public response header

Error code

Error code format

When an error in the user’s access to the API takes place, the system returns the corresponding error code and error message to the user, facilitating to locate the problem and conduct proper processing. When an error occurs in the request, the detailed error message gets returned via the Response Body in the format below:

Example:

{ 
    "code":"IllegalRequestUrl", 
    "message":"The requested url belongs to domain which is not under acceleration",
    "requestId":" 81d0b05f-5ad4-1f22-8068-d5c9de60a1d7" 
}

Common error code

DRDS error code

Definition of specifications for encrypted transmission of the password

All interface parameters involving the password need to be encrypted. Transmitting the password in the form of plaintext is prohibited. All passwords are encrypted by the AES-128-ECB encryption algorithm, with the first 16 bits of the SK as the key. The PKCS5Padding algorithm is used for length completion. In addition, the binary byte stream generated after encryption is converted to the hexadecimal and transmitted to the server in the form of string.

For the encryption process, refer to the following codes. It is described by taking the Python as an example:

# -*- coding: utf-8 -*-
from Crypto.Cipher import AES
from binascii import b2a_hex, a2b_hex
"""
If the package does not exist after calling Cipher package, install the pycryptodome package.
"""

def encrypt(secretkey, password):
    """Encrypt adminpass by AES-128-ECB/PKCS5Padding, the key is secretkey."""
    pendding = 16 - len(password) % 16
    password += chr(pendding) * (pendding)
    return b2a_hex(AES.new(secretkey[:16], AES.MODE_ECB).encrypt(password))

def decrypt(secretkey, password):
     """Decrypt adminpass by AES-128-ECB/PKCS5Padding, the key is secretkey."""
    decrypted = AES.new(secretkey[:16], AES.MODE_ECB).decrypt(a2b_hex(password))
    pendding = ord(decrypted[len(decrypted) - 1])
    return decrypted[:-pendding]

Typesetting agreement