All Products
Search
Document Center

:Request syntax and signature method V2 for RPC APIs

Last Updated:Jan 17, 2024

This topic describes how to construct requests to call Alibaba Cloud API operations in the remote procedure call (RPC) style, including the request syntax, responses, and signature method. You can call Alibaba Cloud API operations in the RPC style by sending HTTP requests. If you want to develop SDKs to call the API operations, you can refer to this topic to learn how to construct HTTP requests for API calls.

Important

The request syntax and signature method V2 are discontinued. Use the request syntax and signature method V3.

HTTP request syntax

The following table describes the components of an Alibaba Cloud API request.

Component

Required

Description

Example

Protocol

Yes

The protocol that is used to send the API request. You can read the API reference of each Alibaba Cloud service to obtain information about the protocol that is used. You can send a request over HTTP or HTTPS. To ensure data security, we recommend that you send requests over HTTPS. Valid values: https:// and http://.

https://

Endpoint

Yes

The endpoint of the Alibaba Cloud service API. Topics that list the endpoints of each Alibaba Cloud service are available. You can view the endpoints of a service in different regions in these topics.

ecs.aliyuncs.com

Common request parameters

Yes

The parameters that must be included in all Alibaba Cloud API requests. For more information, see the Common request parameters section of this topic.

Action

Operation-specific request parameters

No

The request parameters that are specific to the API operation. For more information, visit OpenAPI Portal.

RegionId

HTTPMethod

Yes

The request method of the RPC request. 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. You can search for the API operation that you want to call in OpenAPI Portal.

CreateInstance

Version

String

Yes

The version number of the API. You can view the API version of the service that you want to access in OpenAPI Portal. For example, you can view the API version of Short Message Service (SMS) in OpenAPI Portal. The API version is 2017-05-25.

2014-05-26

Format

String

No

The format in which the response is to be returned. Valid values: JSON and XML. Default value: XML.

JSON

AccessKeyId

String

Yes

The AccessKey ID provided to you by Alibaba Cloud. You can view your AccessKey ID in the Resource Access Management (RAM) console. For more information about how to create an AccessKey pair, see Create an AccessKey pair.

***

SignatureNonce

String

Yes

A unique, random number used to prevent network replay attacks. We recommend that you use different numbers for different requests. The length of the numbers is not limited.

15215528852396

Timestamp

String

Yes

The timestamp of the request. The timestamp is valid for 31 minutes. You must initiate the request within 31 minutes after the timestamp is generated. Specify the time in the ISO 8681 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time must be displayed in UTC.

For example, 2018-01-01T12:00:00Z specifies 20:00:00 on January 1, 2018 in UTC+8.

2018-01-01T12:00:00Z

SignatureMethod

String

Yes

The encryption method of the signature string. Set the value to HMAC-SHA1.

HMAC-SHA1

SignatureVersion

String

Yes

The version number of the signature algorithm. Set the value to 1.0.

1.0

Signature

String

Yes

The signature string of the request. For more information about how to calculate the signature string, see the Signature method section of this topic.

Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D

API request construction

Step 1: Construct a URL

1. Construct a URL for an API request in the following format: <Protocol><Endpoint>?<Common request parameters><Operation-specific request parameters>. For a POST request, we recommend that you include operation-specific request parameters in the request body. This prevents request failures caused by the excessive length of the URL. For a GET request, pass the operation-specific request parameters in the query string.

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 the Timestamp parameter is 2016-02-23T12:46:24Z, the encoded value is 2016-02-23T12%3A46%3A24Z.

Sample URL: 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

You can use only the POST or GET method to call an Alibaba Cloud API operation in the RPC style.

For a GET request, you can send the URL that is constructed in Step 1 by using a tool such as a browser, cURL, or wget.

For a POST request, we recommend that you configure operation-specific request 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 either the JSON or XML format. The default response format is XML. To change the response format, you can specify the Format parameter in a request. 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 line breaks or indentations.

If an API call is successful, a request ID is returned. The HTTP status code is 2xx, which is not displayed in the response. Sample success responses:

  • XML format

<?xml version="1.0" encoding="UTF-8"?> <!--Result Root Node-->
<ActionResponse> <!--Return Request Tag-->
    <RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId> <!--Return Result Data-->
</ActionResponse>
  • JSON format

{
    "RequestId": "4C467B38-3910-447D-87BC-AC049166F216" /* Return Result Data */
}

If an API call fails, a request ID, a service node, an error code, and an error message are returned. The HTTP status code is 4xx or 5xx. Sample failure responses:

  • XML format

<?xml version="1.0" encoding="UTF-8"?><!--Result Root Node-->
<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 on the Alibaba Cloud OpenAPI Diagnostics page based on the request ID that is returned. For more information about error codes, visit the Global error code and Error Codes pages. If the error persists, you can submit a ticket and provide the endpoint and request ID.

Signature method

You must sign all API requests to ensure security. Alibaba Cloud uses the request signature to verify the identity of the API caller. Therefore, each API request must contain signature information, regardless of whether the request is sent by using HTTP or HTTPS. This section describes how to sign API requests.

Step 1: Create a canonicalized query string

1. Arrange the request parameters. Arrange the request parameters in alphabetical order to construct a canonicalized query string. Place parameters starting with uppercase letters before those starting with lowercase letters. These request parameters include all common parameters and operation-specific parameters except the Signature parameter. For more information, see the Common request parameters section of this topic. The following pseudocode shows how to sort parameters:

// Example: Parameters {b, a, C} are sorted as {C, a, b}.
sortParams = sorted(params.keys())

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 as encodeURIComponent. The following pseudocode shows how to encode request parameters and values:

// Example: A request parameter and its value are encoded as %E6%B5%8B%E8%AF%95 and %E4%B8%AD%E6%96%87.
encodeURIComponent(sortParams.keys, sortParams.values)

3. Use an equal sign (=) to concatenate each encoded request parameter and its value. The following pseudocode shows how to concatenate a request parameter and its value:

// Example: The encoded parameter is test and the encoded value of the parameter is testvalue. The parameter and its value can be concatenated as test=testvalue.
encodeURIComponentParam.key=encodeURIComponentParam.value

4. Use ampersands (&) 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. The canonicalized query string is obtained. The canonicalized query string is referred to as CanonicalizedQueryString.

Step 2: Construct a string-to-sign and calculate the signature string

1. Construct a string-to-sign. The following pseudocode shows how to construct a string-to-sign:

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 string by using the string-to-sign and the AccessKey secret of the specified AccessKey ID. You must follow RFC 2104 and use the HMAC-SHA1 algorithm. The following pseudocode shows how to calculate the signature string. In this example, Base64() is the encoding function, HMAC_SHA1() is the function for generating the HMAC_SHA1 value, and UTF_8_Encoding_Of() is the function for UTF-8 encoding. The return value of HMAC_SHA1() is the raw data that is encoded other than a hexadecimal string.

String signature = Base64(HMAC_SHA1(AccessSecret + "&", UTF_8_Encoding_Of(stringToSign)))

You can set the Signature common parameter to the value of the signature parameter.

Signature example

In this example, the DescribeDedicatedHosts operation of Elastic Compute Service (ECS) is called to query the details of one or more dedicated hosts. The AccessKey ID is testid, the AccessKey secret is testsecret, the value of the SignatureNonce parameter is edb2b34af0af9a6d14deaf7c1a5315eb, and the timestamp of the request is 2023-03-13T08:34:30Z. To calculate the signature string, perform the following steps:

  1. Construct a canonicalized query string.

    http://ecs.aliyuncs.com/?AccessKeyId=testid&Action=DescribeDedicatedHosts&Format=JSON&RegionId=cn-beijing&SignatureMethod=HMAC-SHA1&SignatureNonce=edb2b34af0af9a6d14deaf7c1a5315eb&SignatureVersion=1.0&Tag.1.Key=testkey&Tag.1.Value=testvalue&Timestamp=2023-03-13T08%3A34%3A30Z&Version=2014-05-26
  2. Construct a string-to-sign.

    GET&%2F&AccessKeyId%3Dtestid%26Action%3DDescribeDedicatedHosts%26Format%3DJSON%26RegionId%3Dcn-beijing%26SignatureMethod%3DHMAC-SHA1%26SignatureNonce%3Dedb2b34af0af9a6d14deaf7c1a5315eb%26SignatureVersion%3D1.0%26Tag.1.Key%3Dtestkey%26Tag.1.Value%3Dtestvalue%26Timestamp%3D2023-03-13T08%253A34%253A30Z%26Version%3D2014-05-26
  3. Calculate the signature string. In this example, the AccessKey secret is testsecret and the encryption key used for HMAC calculation is testsecret&. The calculated signature string is fRmq1o6saIIjVlawOy+o6jDU9JQ=. The following pseudocode shows how to calculate the signature string:

    String Signature = Base64(HMAC_SHA1(AccessSecret + "&",UTF_8_Encoding_Of(stringToSign)))
  4. Add the Signature=fRmq1o6saIIjVlawOy%2Bo6jDU9JQ%3D string that is encoded based on RFC 3986 to the URL obtained in Step 1.

    https://ecs.cn-beijing.aliyuncs.com/?AccessKeyId=testid&Action=DescribeDedicatedHosts&Format=JSON&RegionId=cn-beijing&SignatureMethod=HMAC-SHA1&SignatureNonce=edb2b34af0af9a6d14deaf7c1a5315eb&SignatureVersion=1.0&Tag.1.Key=testkey&Tag.1.Value=testvalue&Timestamp=2023-03-13T08%3A34%3A30Z&Version=2014-05-26&Signature=fRmq1o6saIIjVlawOy%2Bo6jDU9JQ%3D
Important

The API version that you specify must match the endpoint that you use. Otherwise, an InvalidVersion error occurs. You can view the API version and endpoints of an Alibaba Cloud service on the homepage of the service in OpenAPI Explorer.

After you obtain the new URL in Step 4, you can use a tool, such as a browser, 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 encoding method in this step is referred to as encodeURIComponent. Encode the request parameters and values based on the following encoding rules:

  • Uppercase letters, lowercase letters, digits, hyphens (-), underscores (_), periods (.), and tildes (~) do not need to be encoded.

  • Other ASCII characters must be encoded in the %XY format. XY represents the ASCII code of the characters in hexadecimal notation. For example, double quotation marks (") are encoded as %22.

  • Non-ASCII characters are encoded in UTF-8.

  • Spaces must be encoded as %20. Do not encode spaces as plus signs (+).

References

Check the styles of APIs section of the "API styles" topic