General Description
Certification
Before using the DNS API, real-name authentication is required. If you have not completed real-name authentication, please go to the Official Website Console under security certification to perform real-name authentication. Refer to [Real-Name Authentication Operations](UserGuide/Certification/Basic Introduction to Real-name Verification.md).
When users who have not passed real-name authentication submit API requests, the following error code will be returned:
| Error return codes | Error message | Status code | Description |
|---|---|---|---|
| QualifyNotPass | The User has not pass qualify. | 403 | The account has not passed certification |
API authentication mechanism
Users can interact with Baidu AI Cloud in two ways: authenticated mode and anonymous mode. In authenticated mode, the identity of the sender must be verified using encryption with the Access Key ID/Secret Access Key. The Access Key ID (AK) identifies the user, while the Secret Access Key (SK) is used both to encrypt the authentication string by the user and to verify the authentication string by Baidu AI Cloud. The SK must remain confidential and is known only to the user and Baidu AI Cloud.
When Baidu AI Cloud receives a user's request, the system will use the same SK and identical certification mechanism to generate a certification string, and then compare it with the certification string included in the user's request. If the authentication strings are the same, the system considers that the user possess the specified operation permission and proceeds with the relevant executions. If the authentication strings differ, the system will skip this operation and returns an error code. For detailed information on the authentication mechanism, please refer to [Authentication Mechanism](Reference/Authentication mechanism/Introduction.md).
Communication protocol
Both HTTP and HTTPS methods are supported. For better data security, it is recommended to use HTTPS.
Definition of password encryption transmission specification
All API parameters involving passwords must be encrypted, and plaintext transmission is strictly prohibited. Passwords are encrypted using the AES 128-bit encryption algorithm, with the first 16 bits of the SK serving as the key. The binary byte stream generated post-encryption must be converted into a hexadecimal format and transmitted to the server as a string. The steps are as follows:
- byte[] bCiphertext = AES(plaintext, SK)
- String strHex = HexStr(bCiphertext)
Idempotence
When invoking the creation API, if a timeout or an internal server error occurs, the user can retry the request. In such cases, the clientToken parameter ensures no extra resources are created, thereby maintaining the request's idempotence.
Idempotence is based on clientToken, which is an ASCII string with a length not exceeding 64 bits, usually placed in the query string, such as http://bcc.bj.baidubce.com/v1/instance?clientToken=be31b98c-5e41-4838-9830-9be700de5a20.
If the same clientToken value is used when calling the creation API, the server will return the same result. If a retry is necessary due to an error, supplying the same clientToken ensures that only one resource is created. If the clientToken has been used previously but other parameters like queryString, requestBody, or even the URL Path differ, an error code of IdempotentParameterMismatch will be issued.
The clientToken remains valid for 24 hours from the last time it was received by the server. In cases where the same clientToken is continuously sent, it will stay valid indefinitely within that time window.
Typesetting conventions
| Typesetting format | Meaning |
|---|---|
| < > | Variable |
| [ ] | Optional |
| { } | Mandatory |
| | | Mutually exclusive relationship |
| Monospace font Courier New | Screen output |
Request structure description
The data exchange format is JSON, and all request and response body content is encoded in UTF-8.
Request parameters include the following 4 types:
| Parameter type | Description |
|---|---|
| URI | It is usually used to specify the operation entity, for example: PUT /v1/privatezone/{zoneId} |
| Query | Request parameters carried in the URL |
| HEADER | It is passed in through HTTP header, such as: x-bce-date |
| RequestBody | Request data body organized in JSON format |
Response structure description
Response values are in two forms:
| Response content | Description |
|---|---|
| HTTP STATUS CODE | Such as 200, 400, 403, 404, etc. |
| ResponseBody | Response data body organized in JSON format. |
Common request header and common response header
Common request headers
| Common header | Description |
|---|---|
| Authorization | Include both the Access Key and the request signature. |
| Content-Type | application/json; charset=utf-8。 |
| x-bce-date | A string representing the date that complies with API specifications. |
Standard HTTP protocol header fields are not included in this list. Key header fields are required for all network diagnosis APIs. For POST, PUT, DELETE, and similar requests, data should be placed in the request body.
Common response headers
| Common header | Description |
|---|---|
| Content-Type | application/json; charset=utf-8。 |
| x-bce-request-id | These headers are generated by the VPC backend and automatically included in the response header. |
API version history
| Parameters | Types | Parameter location | Description | Required or not |
|---|---|---|---|---|
| version | String | URL parameter | API version number: The current API version is v1. | Yes |