Public parameters include public request parameters and public response parameters.
- Public request parameters: the request parameters that every API must use.
- Public response parameters: the parameters returned after an API is called, regardless of whether the call is successful or not.
Public request parameters
The following table lists all the public request parameters for the HiTSDB open APIs.
Name | Type | Required | Description |
---|---|---|---|
Format | String | No | Type of the returned value. Value options: JSON and XML. |
Action | String | Yes | Name of the API to be called. |
Version | String | Yes | API version number. Format: YYYY-MM-DD (date). The current version is 2017-06-01. |
AccessKeyId | String | Yes | Key ID that Alibaba Cloud issues to you for service access. |
SignatureMethod | string | Yes | Signature method. Currently, HMAC-SHA1 is supported. |
Timestamp | String | Yes | Time stamp of a request. The date format follows the ISO8601 standard and uses UTC time. Format: YYYY-MM-DDThh:mm:ssZ, for example, 2013-08-15T12:00:00Z (20:00:00, January 10, 2013, Beijing time). |
SignatureVersion | String | Yes | Signature algorithm version. The current version is 1.0. |
SignatureNonce | String | Yes | Unique random number, used to prevent replay attacks. You must use different random numbers for different requests. |
RegionId | String | Yes | ID of the region in which the HiTSDB instance is located. |
Signature | String | Yes | Signature result string. For information about the signature calculation method, see Signature mechanism. |
Public response parameters
The public response parameter for the HiTSDB open APIs is the “RequestId”, a unique identifier. “RequestId” identifies each API call request, and is often used for API troubleshooting.
Example (XML)
<?xml version="1.0" encoding="utf-8"?>
<!—Result root node-->
<Interface name+Response>
<!—Return request tag-->
<RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId>
<!—Returned results-->
...
</Interface name+Response>
Returned results
After the API service is called, data is returned in a unified format.
- If the returned HTTP status code is 2xx, the call was successful.
- If the returned HTTP status code is 4xx or 5xx, the call failed.
For successful calls, the commonly used formats of returned data are XML and JSON. When a request is sent, an external system can input parameters to specify the format of the returned data. JSON is recommended.
In this document, examples of returned results are formatted in a way that is easier for users to view. The actual returned results do not contain line breaks, indentation, or other layouts.
Successful results
Returned XML results include the request processing result (successful or failed) and the specific service data.
XML
<?xml version="1.0" encoding="utf-8"?>
<!—Result root node-->
<Interface name+Response>
<!—Return request tag-->
<RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId>
<!—Returned result data-->
...
</Interface name+Response>
JSON
{
/* Returned request ID */
"RequestId": "4C467B38-3910-447D-87BC-AC049166F216",
/* Returned results*/
...
}
Error results
When an error occurs in an API call, no result is returned. The caller can identify the cause of the error according to the error code.
When an error occurs in a call, the following information is returned for a HTTP request:
- An HTTP status code: 4xx or 5xx;
- A specific error code and error message;
- A globally unique RequestId;
- ID of the site this request accesses: HostId.
If the caller cannot identify the cause of the error, the caller can contact Alibaba Cloud Customer Service and provide the HostId and RequestId to help us solve the problem as quickly as possible.
XML
<?xml version="1.0" encoding="UTF-8"?>
<Error>
<RequestId>8906582E-6722-409AA6C4-0E7863B733A5</RequestId>
<HostId>hitsdb.aliyuncs.com</HostId>
<Code>UnsupportedOperation</Code>
<Message>The specified action is not supported.</Message>
</Error>
JSON
{
"RequestId": "7463B73D-35CC-4D19-A010-6B8D65D242EF",
"HostId": "hitsdb.aliyuncs.com",
"Code": "UnsupportedOperation",
"Message": "The specified action is not supported."
}