Overview
This topic describes the invocation method for Alibaba Cloud APIs in the remote procedure call (RPC) style. This topic also describes how to develop SDKs in the RPC style. If you want to use Alibaba Cloud SDKs, see the documentation of Alibaba Cloud SDKs.
Alibaba Cloud RPC APIs can be used to send API requests over HTTP. This topic describes how to send API requests over HTTP.
This topic describes the parameters of RPC API requests. This topic also describes how to obtain an API request by arranging the parameters and how to obtain the response to the API request.
HTTP request structure
The following table describes the parameters that are included in a complete Alibaba Cloud API request.
Parameter | Required | Description | Example |
Protocol | Yes | You can view the API reference of each Alibaba Cloud service to configure this parameter. You can send a request over | https:// |
Endpoint | Yes | Topics that list the endpoints of each Alibaba Cloud service are available. You can view the endpoints of a service in different regions in the topics. For more information, see the "Configure an endpoint" topic. | ecs.aliyuncs.com |
Common request parameters | Yes | Common request parameters must be included in all Alibaba Cloud API requests. For more information, see the Common request parameters section of this topic. | |
Operation-specific request parameters | No | The request parameters that are specific to an API operation. For more information, visit OpenAPI Explorer. | |
HTTPMethod | Yes | The request method of an RPC API. Valid values: POST and GET. | GET |
Common request parameters
The following table describes the common request parameters of Alibaba Cloud API requests.
Parameter | Type | Required | Description | Example |
Action | String | Yes | The operation that you want to perform. To search for the API operation that you want to call, visit OpenAPI Explorer. | CreateInstance |
Version | String | Yes | The version number of the API. To view the API version of the API operation that you want to call, visit OpenAPI Explorer. | 2014-05-26 |
Format | String | No | The format in which to return the response. Valid values: JSON and XML. Default value: XML. | JSON |
AccessKeyId | String | Yes | The AccessKey ID provided to you by Alibaba Cloud. To view your AccessKey ID, go to the RAM console. For more information about how to create an AccessKey pair, see Obtain an AccessKey pair. | *** |
SignatureNonce | String | Yes | A unique, random number used to prevent replay attacks. You must use different numbers for different requests. | 15215528852396 |
Timestamp | String | Yes | The timestamp of the request. Specify the time in the ISO 8601 standard in the For example, | 2018-01-01T12:00:00Z |
SignatureMethod | String | Yes | The encryption method of the signature string. Set the value to | HMAC-SHA1 |
SignatureVersion | String | Yes | The version of the signature encryption algorithm. Set the value to | 1.0 |
Signature | String | Yes | The signature string of the current request. For more information about how signatures are calculated, see Signature method. | Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D |
Request structure
Step 1: Construct a URL
1. A URL for an API request is constructed in the following format: <Protocol><Endpoint>?<Common request parameters><Operation-specific parameters>
. To prevent request failures caused by the excessive length of URLs, we recommend that you include operation-specific parameters
in the body of POST requests.
2. Encode the request parameters. For more information about encoding rules, see the Encoding rules section of this topic. For example, if the value of Timestamp is 2016-02-23T12:46:24Z, the encoded value is 2016-02-23T12%3A46%3A24Z.
URL example: http://ecs.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeDedicatedHosts&Format=XML&SignatureNonce=3ee8c1b8-xxxx-xxxx-xxxx-xxxxxxxxx&Version=2014-05-26&AccessKeyId=testid&Signature=OLeaidS1JvxuMvnyHOwuJ%2BuX5qY%3D&SignatureMethod=HMAC-SHA1&Timestamp=2016-02-23T12%3A46%3A24Z&RegionId=cn-hangzhou&Status=Available
Step 2: Initiate an API request
The request method of an Alibaba Cloud RPC API can be GET or POST.
If you want to send an HTTP GET request, you can use the URL in Step 1 by using a browser or a tool, such as cURL or Wget.
If you want to send an HTTP POST request, we recommend that you configure operation-specific parameters in the request body. You must set the Content-Type request header to application/x-www-form-urlencoded
.
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. 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.
If an API call is successful, the response of the call contains a request ID and HTTP status code 2xx. Examples:
XML format
<?xml version="1.0" encoding="UTF-8"?> <!--The root node of the result-->
<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 of the responses-->
<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 API call fails, you can troubleshoot the error in OpenAPI Explorer - Diagnose based on the return value of RequestId. For more information about error codes, visit the API Error Center or see Common error codes. If the error persists, you can submit a ticket and provide the values of HostId and RequestId.
Request signatures
Alibaba Cloud uses the request signature to verify the identity of the API caller. This ensures data security when you call API operations. Each API request must contain a signature, regardless of whether the request is sent over HTTP or HTTPS. This section describes how to sign API requests.
Step 1: Create a canonicalized query string
1. Arrange the request parameters. Create a canonicalized query string by arranging the request parameters in alphabetical order. These request parameters include all common parameters and operation-specific parameters except Signature
. For more information, see the Common request parameters section of this topic.
2. Encode the request parameters and values. Encode the request parameters and values in UTF-8 based on RFC 3986. For more information, see the Encoding rules section of this topic. The encoding method in this step is referred to encodeURIComponent
.
3. Use an equal sign (=) to concatenate each encoded request parameter and its value.
4. Use ampersand (&) to concatenate the encoded request parameters. The parameters must be arranged in the same order as the parameters in the first step of Step 1
.
5. Add a protocol and an endpoint to the request header. Example: https://ecs.aliyuncs.com.
This way, the canonicalized query string is obtained. The query string is referred to CanonicalizedQueryString
.
Step 2: Create a string-to-sign
1. Configure the stringToSign
parameter to create a string-to-sign. The following example shows how to create a string-to-sign in SDKs for Java:
String stringToSign = HTTPMethod + "&" + // HTTPMethod specifies the HTTP method that is used to send a request, such as GET. encodeURIComponent("/") + "&" + // encodeURIComponent specifies the encoding method that is used in the second step of Step 1. encodeURIComponent(CanonicalizedQueryString) // CanonicalizedQueryString specifies the canonicalized query string that is obtained in Step 1.
2. Calculate the signature value by using StringToSign
and the AccessKey secret of the specified AccessKey ID. You must follow RFC 2104 and use the HMAC-SHA1
algorithm. The following example shows how to calculate the signature value in SDKs for Java:
String signature = Base64(HMAC_SHA1(AccessSecret, UTF_8_Encoding_Of(stringToSign)))
The value of the common request parameter Signature is signature
.
Signature example
In this example, the DescribeDedicatedHosts operation of Elastic Compute Service (ECS) is used to describe how to query the details about one or more dedicated hosts. If you set AccessKeyID to testid and set AccessKeySecret to testsecret, you can perform the following steps:
Construct a canonicalized query string.
http://ecs.aliyuncs.com/?Timestamp=2016-02-23T12%3A46%3A24Z&Format=XML&AccessKeyId=testid&Action=DescribeDedicatedHosts&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-xxxx-xxxx-xxxx-xxxxxxxxxx&Version=2014-05-26&SignatureVersion=1.0
Configure the
stringToSign
parameter to create a string-to-sign.GET&%2F&AccessKeyId%3Dtestid%26Action%3DDescribeDedicatedHosts%26Format%3DXML%26SignatureMethod%3DHMAC-SHA1%26SignatureNonce%3D3ee8c1b8-xxxx-xxxx-xxxx-xxxxxxxxx%26SignatureVersion%3D1.0%26Timestamp%3D2016-02-23T12%253A46%253A24Z%26Version%3D2014-05-26
Calculate the signature value. The key that is used to calculate the signature value is
testsecret&
because AccessKeySecret is set totestsecret
. The signature value isOLeaidS1JvxuMvnyHOwuJ+uX5qY=
. In this example, the JavaBase64 encoding scheme is used.String Signature = Base64(HMAC_SHA1(AccessSecret,UTF_8_Encoding_Of(stringToSign)))
Add the Signature=OLeaidS1JvxuMvnyHOwuJ%2BuX5qY%3D string that is encoded based on
RFC 3986
to the URL in Step 1.http://ecs.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeDedicatedHosts&Format=XML&SignatureNonce=3ee8c1b8-xxxx-xxxx-xxxx-xxxxxxxxx&Version=2014-05-26&AccessKeyId=testid&Signature=OLeaidS1JvxuMvnyHOwuJ%2BuX5qY%3D&SignatureMethod=HMAC-SHA1&Timestamp=2016-02-23T12%253A46%253A24Z
After you obtain the new URL in Step 4, you can use a browser or a tool such as cURL or Wget to send an HTTP request to call the DescribeDedicatedHosts
operation. This operation is used to query the details about one or more dedicated hosts.
Appendix
Encoding rules
When you call Alibaba Cloud API operations, you must encode the request parameters and values in UTF-8 based on RFC 3986. The following lists describe the rules:
Uppercase letters, lowercase letters, digits, and specific special characters such as hyphens (
-
), underscores (_
), periods (.
), and tildes (~
) do not need to be encoded.Encode other ASCII characters. Other characters must be percent encoded in %XY format. XY represents the ASCII code of the characters in hexadecimal notation. For example, double quotation marks (
"
) are encoded as%22
.Encode non-ASCII characters in UTF-8.
Spaces must be encoded as
%20
. Do not encode spaces as plus signs+
.
The encoding method in this step is referred to as encodeURIComponent
.