The product is a global product, with the domain name of bss.bj.baidubce.com.

The data exchange format is JSON, and all request/response body contents are encoded in UTF-8.The IPs used in the URL parameters are expressed in dotted decimal.

Identity Verification

The users using IDS API need real-name authentication, and those who do not pass the real-name authentication can go to the Baidu Open Cloud Console for authentication. Users who fail to pass identity verification will get the following error code when requesting:

Error code	Err description	HTTP status code	Explanation
QualifyNotPass	The User has not pass qualify.	403	Account has not passed identity verification

API Authentication Mechanism

The security authentication of all APIs utilizes the Access Key and request signature mechanism. Access Key consists of Access Key ID and Secret Access 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 Baidu Cloud 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 privilege, 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.

Communication Protocol

Currently, IDS API only supports HTTP calling method, and does not support HTTPS call.

Description of Request Structure

The request parameters include the 4 kinds below:

Parameter Type	Description
URI	In general, it is used to indGET /v2/securityAudit/postpayStatus
Query parameter	Request parameters carried in URL.
HEADER	Passed by the HTTP header, e.g. x-bce-date.
RequestBody	Request data body organized in JSON format.

Description of Response Structure

There are two types of return values:

Return Content	Description
HTTP STATUS CODE	E.g. 200,400,403,404, etc.
ResponseBody	Response data body organized in JSON format.

API Version Number

Parameter	Type	Parameter position	Description	Required or not
version	String	URL parameter	API version No., the current value is 2.	Yes

Idempotency

If a request timeout or internal server error occurs when the create interface is called, the user may try to resend the request. At this time, the user can avoid creating more resources than expected through the clientToken parameter, that is, to ensure the idempotence 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.baidubce.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.

Transmission Specification for Password Encryption

All password-involved interface parameters should be encrypted, and forbidden to be transmitted in clear text. All passwords utilize the AES 128-bit encryption algorithm for encryption, and the first 16 bits of SK are utilized as the key. The binary byte streams generated after encryption should be converted into the sexadecimal byte streams, and transmitted to the service side in the form of strings. The specific procedures are as follows:

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

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.

Normalized String

Generally, one string can include any Unicode character. In programming, this kind of flexibility will bring about numerous troubles. Therefore, the concept of "normalized string" is introduced. One normalized string only includes the percent-encoding characters and URI (Uniform Resource Identifier) unreserved characters.

RFC 3986 stipulates that "URI non-reserved characters" include the following characters: Letters (A-Z, a-z), numbers (0-9), hyphen (-), dot mark (.), underline (_), tilde (~).

The method to change any string into a normalized string is:

• To convert strings into UTF-8 encoded byte stream.
• To keep all "URI non-reserved characters" unchanged.
• To make the Percent-encoding specified in RFC 3986 once for the rest bytes, namely, two sexadecimal strings representing the byte value are behind one "%". All the letters are in upper case.

Example:

Original string: This is an example for test, Corresponding specification string: this%20is%20an%20example%20for%20%E6%B5%8B%E8%AF%95.