Request sstructure

Request structure introduction

1. API Service Domain Name

Service Domain Name of the RDS API includes:

2. Communications Protocol

API calls follow HTTP protocol, and each Region adopts different domain names. The specific domain name is rds.{region}.baidubce.com.

3. Request Parameter

Two types of parameters should be specified for each request of Baidu AI Cloud API, namely, common request parameter and interface request parameter. Of which, the common request parameter is the request parameter for every interface, and the interface request parameter is the specific parameter for each interface. See the description of the Request Parameter of each interface.

The request parameters include the following four types:

4. API version number

5. Character Encoding

Content can be parsed, and UTF-8 encoding is adopted for all request/response body contents for now. Support more encoding types later.

Common header

Common Request Header

The standard header field of the HTTP protocol is no longer listed here. The Common header field appears in each RDS API, which is a required header field. The x-bce-content-sha256 header field appears only in POST and PUT requests. POST, PUT, DELETE, and other request data are placed in the request body.

Common Response Header

Interface special request parameter instruction

The interface request parameter is related with a specific interface, and interface request parameters supported by different interfaces vary from one another.

Take Query Instance List as an example, and the supported interface request parameters are as follows:

Instruction for each field is as follows:

Final request form

The final request is composed of the following parts:

1. Request domain name: For example, Beijing Zone’s domain name is rds.bj.baidubce.com.
2. Request path The interface request paths vary from one another. See Interface Details.
3. Request method: Support request method of RESTful and this interface file involves four methods like POST, GET, PUT, and DELETE.
4. Request header common request header, including authentication information. See the [Common Header](#Common Header) for details.
5. Parameter string of final request: Including interface path parameters (behind the question mark in request path) and interface request parameters. For example, the path parameter readReplica and interface request parameter clientToken={clientToken} for creation of read-only instance.
6. Request body: json structure that is composed of RequestBody parameter structures according to interface provisions.

Example:

POST /v1/instance/readReplica&clientToken={be31b98c-5e41-4838-9830-9be700de5a20} HTTP/1.1
Host: rds.bj.baidubce.com
Content-Type: application/json
x-bce-content-sha256: fc2af5fb07f6acdf3981dfe4f02d23a3585e93f618b81876abee98ed268cf
x-bce-date 2018-02-06T08:33:37Z
Authorization bce-auth-v1/d2f57e2b0b1611e89c59c56590fe827b/2018-02-06T08:33:37Z/3600/host;x-bce-account;x-bce-client-ip;x-bce-date;x-bce-request-id;x-bce-security-token/fc2af5fb07f6704f118641f75ea4f02d23a3585e93f618b81876f5d210fb8be4

{
    "billing":{
       "paymentTiming":"Postpaid"
    },
    "sourceInstanceId": "rds-mudjimy0jbig",
    "cpuCount":1,
    "memoryCapacity":0.25,
    "volumeCapacity":5
}

Return results

Return correct result

Cloud database RDS’s API service requires that details returned by one request are described using JSON structure. See the example below for the correct result return format.

HTTP/1.1?200?OK
x-bce-request-id?1214cca7-4ad5-451d-9215-71cb844c0a50
Date:?Wed,?03?Dec?2014?06:42:19?GMT
Content-Type:?application/json;charset=UTF-8
Server:?BWS
{
    "instanceIds":?[
    "i-T1I3OtUO"
    ]
}

Returnn error

When an error occurs in the request, the detailed error message is returned via the Response Body in the format below:

Example:

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

Instruction on the RDS error return code

Signature authentication

The RDS API authenticates every access request to ensure user security. Access Key and request signature are used for security authentication. The Access Key consists of an Access Key ID and a Secret Access Key, both of which are strings and granted to users by Baidu AI Cloud. Access Key ID is used to indicate user identity. Access Key Secret is the key used to encrypt the signature string and to verify the signature string on the server side, so it must be strictly kept confidential.

In response to every HTTP request, the user needs to generate a signature string according to the method mentioned below and put the authentication string into the Authorization header field requested by HTTP.

Signature String Format

bce-auth-v{version}/{accessKeyId}/{timestamp}/{expireTime}/{signedHeaders}/{signature}

Signature application steps

See Get AK/SK to Get AK/SK.

Signature generation algorithm

See Authentication and Certification Mechanism for signature generation algorithm.

Other descriptions

Definition of password encryption and transmission specification

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

For the encryption process, see the following codes, taking 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]

Idempotency

If the user encounters a request timeout or an internal error of the server when calling the creation interface, the user may try to resend the request. In this case, the user avoids creating more resources than expected via the clientToken parameter, which is to guarantee the idempotency of the request.

Idempotency 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://rds.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 when retrying an error. If the user provides a used clientToken, and other request parameters (including the queryString and requestBody) are different url Path is different, it returns to 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, if the client sends the same clientToken always, then this clientToke is valid for a long time.

Date and time specification

There are many ways to represent the date and time. 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:

1. The date is indicated in the form of YYYY-MM-DD. For example, 2014-06-01 represents June 1, 2014.
2. The time is indicated in the form of hh: mm: ss, and an upper case Z is added at the end to indicate the UTC time. For example, 23:00:10Z represents PM 23:00:10 UTC time.
3. When it involves the combined indication of date and time, an upper case T is added between date and time. For example, 2014-06-01T23:00:10Z represents PM 23:00:10 UTC time on June 1, 2014.

Agreed typesetting