To call the Dedicated Host (DDH) API, you must send an HTTP or HTTPS GET request to the DDH endpoint. You must add the request parameters specific to related API operations. After you call an API operation, the system returns a response. The request and response are encoded in UTF-8.

Request syntax

The API operations for DDH use the Remote Procedure Call (RPC) protocol. You can call the API operations by sending HTTP or HTTPS GET requests.

The following request syntax is used: 
http(s)://Endpoint/?Action=xx&Parameters
where:
  • Endpoint: the endpoint of the DDH API is ecs.aliyuncs.com.
  • Action: the name of the operation that you want to perform. For example, to query the details of one or more dedicated hosts, you must set the Action parameter to DescribeDedicatedHosts.
  • Version: the version of the API. The version of the DDH API is 2014-05-26.
  • Parameters: the request parameters for the operation. Separate multiple parameters with ampersands (&).

    Request parameters include common parameters and operation-specific parameters. Common parameters include the API version number and identity verification information. For more information, see Common parameters and Signature method.

In the following sample, the DescribeDedicatedHosts operation is called to query the details of the dedicated hosts in a region.
Note The sample request is formatted to improve readability. 
http(s)://ecs.aliyuncs.com/?Action=DescribeDedicatedHost
&Format=xml
&Version=2014-05-26
&Signature=xxxx%xxxx%3D
&SignatureMethod=HMAC-SHA1
&SignatureNonce=15215528852396
&SignatureVersion=1.0
&AccessKeyId=key-test
&TimeStamp=2012-06-01T12:00:00Z
&RegionId=cn-hangzhou
...

Responses

Responses can be returned in the JSON or XML format. The default response format is XML. To change the response format, you can configure the common request parameter Format in requests. For more information, see Common parameters. The sample responses that are provided in the API reference are formatted with line breaks and indentations for better readability. The actual responses do not have newlines or indentations.

API responses use the HTTP response format. HTTP status codes from 200 to 299 indicate a successful call. Examples:
  • XML format 
    <?xml version="1.0" encoding="UTF-8"?> <!--The root node of the response-->
<ActionResponse> <!--Return request tag-->
    <RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId> <!--Returned results-->
</ActionResponse>
  • JSON format 
    {
    "RequestId": "4C467B38-3910-447D-87BC-AC049166F216" /* Returned results */
}
If an API call fails, the response of the call contains an error code, error message, request ID, and HTTP status code 4xx or 5xx. Examples:
  • XML format 
    <?xml version="1.0" encoding="UTF-8"?><!--The root node the response-->
<Error>
    <RequestId>540CFF28-407A-40B5-B6A5-74Bxxxxxxxxx</RequestId> <!--Request ID-->
    <HostId>ecs.aliyuncs.com</HostId> <!--Service node-->
    <Code>MissingParameter.CommandId</Code> <!--Error code-->
    <Message>The input parameter “CommandId” that is mandatory for processing this request is not supplied.</Message> <!--Error message-->
</Error>
  • JSON format 
        {
    "RequestId": "540CFF28-407A-40B5-B6A5-74Bxxxxxxxxx", /* Request ID */
    "HostId": "ecs.aliyuncs.com", /* Service node */
    "Code": "MissingParameter.CommandId", /* Error code */
    "Message": "The input parameter “CommandId” that is mandatory for processing this request is not supplied." /* Error message */
}

If an error occurs when you call an API operation, you can troubleshoot the error based on the returned error code. For more information, see Common error codes or visit the API Error Center.