Get started with the request syntax and signature method V2 for ROA APIs - Alibaba Cloud SDK

This topic describes how to construct requests to call Alibaba Cloud API operations in the resource-oriented architecture (ROA) style, including the request syntax, responses, and signature method. You can send HTTP requests to call Alibaba Cloud API operations in the ROA style. If you want to develop SDKs to call the API operations, you can read 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 learn 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.	cs.aliyuncs.com
resource_URI_parameters	Yes	The identifier of the resource that you want to access.	/clusters/{cluster_id}/triggers
RequestHeader	Yes	The request headers. In most cases, information such as the API version number, hostname, and authentication information is included. For more information, see the Request headers section of this topic.	x-acs-action
RequestBody	Yes	The operation-specific parameters in the request body. For more information, visit OpenAPI Explorer.	cluster_id
HTTPMethod	Yes	The HTTP method that is used to send the request. Valid values: PUT, POST, GET, and DELETE.	POST

Request headers

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

Header	Type	Required	Description	Example
x-acs-action	String	Yes	The operation that you want to perform. You can search for the API operation that you want to call in OpenAPI Explorer.	CreateTrigger
x-acs-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 Explorer.	2015-12-15
Accept	String	No	The format in which the response is returned. Set the value to `application/json`.	application/json
Authorization	String	Yes if the request is non-anonymous	The authentication information that is used to verify the validity of the request. Specify the value in the `AccessKeyId:Signature` format. The AccessKeyId parameter specifies the AccessKey ID provided to you by Alibaba Cloud. You can view your AccessKey ID in the Resource Access Management (RAM) console. For information about how to create an AccessKey pair, see Obtain an AccessKey pair. The Signature parameter specifies the signature string of the request. For more information, see the Signature method section of this topic.	acs testid:D9uFJAJgLL+dryjBfQK+YeqGtoY=
x-acs-signature-nonce	String	No	A unique, random number used to prevent replay attacks. We recommend that you use different numbers for different requests.	15215528852396
Date	String	Yes	The timestamp of the request. The timestamp is valid for 15 minutes. You must initiate the request within 15 minutes after the timestamp is generated. Specify the time in Greenwich Mean Time (GMT) in compliance with HTTP 1.1. Example: Tue 9 Apr 2019 07:35:29 GMT.	Tue 9 Apr 2022 07:35:29 GMT
x-acs-signature-method	String	Yes if the request is non-anonymous	The encryption method of the signature string. Set the value to `HMAC-SHA1`.	HMAC-SHA1
Content-MD5	String	No	The 128-bit MD5 hash value of the HTTP request body. The hash value is encoded in Base64.	Gtl/0jNYHf8t9Lq8Xlpaqw==
Host	String	Yes	The endpoint of the Alibaba Cloud service API. For more information, see the HTTP request syntax section of this topic.	cs.aliyuncs.com

API request construction

A complete API request consists of the following parts:

HTTPMethod /resource_URI_parameters
RequestHeader
RequestBody

Request parameters contain common request headers and operation-specific parameters. The common request headers contain information such as the API version number and authentication information.

HTTPMethod: the HTTP method that is used to send the request. Valid values: PUT, POST, GET, and DELETE. For more information, see the HTTP request syntax section of this topic.
resource_URI_parameters: the identifiers of the resources that you want to access. Example: /cluster. For more information, see the HTTP request syntax section of this topic.
RequestHeader: the request headers. In most cases, information such as the API version number, endpoint, and authentication information is included. For more information, see the HTTP request syntax section of this topic.
RequestBody: the operation-specific parameters in the request body. For more information, see the HTTP request syntax section of this topic.

Sample request:

POST /clusters/test_cluster_id/triggers HTTP/1.1
{
  	"x-acs-action":"CreateTrigger",
    "x-acs-version":"2015-12-15",
    "Accept":"application/json",
    "Authorization": "acs testid:D9uFJAJgLL+dryjBfQK+YeqGtoY=",
    "x-acs-signature-nonce":"15215528852396",
    "Date":"Tue 9 Apr 2022 07:35:29 GMT",
    "x-acs-signature-method":"HMAC-SHA1",
    "Content-MD5":"Gtl/0jNYHf8t9Lq8Xlpaqw=="
    "Host":"cs.aliyuncs.com"    
}
{
  	"cluster_id":"test_cluster_id",
  	"project_id":"default/nginx-test",
  	"action":"redeploy",
  	"type":"deployment"
}

Encoding

Requests and responses are encoded in UTF-8.

Responses

Each response returns a unique request ID regardless of whether the request is successful. All responses are returned in a unified format. 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 response:

{
    "RequestId": "4C467B38-3910-447D-87BC-AC049166F216" /* The request ID. */
}

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 response:

{
    "code": "400", /* The error code. */
    "message": "Cluster permission denied", /* The error message. */
    "requestId": "A026BC61-0523-5A6D-A5F3-314A3D92FD50", /* The request ID. */
    "status": 400 /* The HTTP status code. */
}

If an API call fails, you can troubleshoot the error on the OpenAPI problem diagnosis page based on the returned value of the RequestId parameter. 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. For more information about the endpoint, see the HTTP request syntax section of this topic.

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. 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.

For each HTTP or HTTPS request, Alibaba Cloud uses the request signature to verify the identity of the API caller. You must perform the following steps to sign a request:

Step 1: Construct canonicalized headers
Step 2: Construct canonicalized resources
Step 3: Construct a string-to-sign
Step 4: Calculate the signature string
Step 5: Add the signature string to the request

Step 1: Construct canonicalized headers

Canonicalized headers are non-standard HTTP headers whose names are prefixed with x-acs- in the request. You can perform the following steps to construct canonicalized headers:

Convert all HTTP header names prefixed with x-acs- to lowercase letters. For example, convert X-acs-Meta-Name: TaoBao to
x-acs-meta-name: TaoBao. Header names are not case-sensitive. We recommend that you use lowercase letters.
If a header value is too long, replace specific delimiters with spaces. The delimiters are \t, \n, \r, and \f.
Sort all HTTP headers that you obtained in the previous step in alphabetical order.
Delete all spaces on both sides of the delimiter that separates the name and value of each header. For example, convert x-acs-oss-meta-name :TaoBao,Alipay to x-acs-oss-meta-name:TaoBao,Alipay.
Append the \n delimiter to the end of each header, including the last header, and concatenate all the headers.

Step 2: Construct canonicalized resources

Canonicalized resources are the canonical descriptions of the resources that you want to access. You can perform the following steps to construct canonicalized resources:

Sort the parameters in the query string of the request by name in alphabetical order and concatenate the parameters by using ampersands (&) to generate the sorted query string.
Concatenate the requested resource path with the sorted query string by using a question mark (?) to obtain canonicalized resources. The resource path is the part between the endpoint and the query string. The path includes the forward slash (/) following the endpoint but excludes the question mark (?) preceding the query string. If the request does not contain a query string, use the resource path as the canonicalized resource.

Example:

Original request URL:

http://demo-product.aliyuncs.com/instances?status=ONLINE&group=test_group

Canonicalized resources:

/instances?group=test_group&status=ONLINE

Step 3: Construct a string-to-sign

Construct a string-to-sign based on the following pseudocode:

String stringToSign = 
    HTTPMethod + "\n" +
    Accept + "\n" +
    ContentMD5 + "\n" +
    ContentType + "\n" +
    Date + "\n" +
    CanonicalizedHeaders +
    CanonicalizedResource

Parameter	Description
HTTPMethod	The HTTP method in uppercase letters, such as POST or GET.
Accept	The value of the Accept header. Set the value to an empty string if this header does not exist.
ContentMD5	The value of the Content-MD5 header. Set the value to an empty string if this header does not exist.
ContentType	The value of the Content-Type header. Set the value to an empty string if this header does not exist.
Date	The value of the Date header.
CanonicalizedHeaders	The canonicalized headers that are obtained from Step 1: Construct canonicalized headers of this topic.
CanonicalizedResource	The canonicalized resources that are obtained from Step 2: Construct canonicalized resources of this topic.

Step 4: Calculate the signature string

Calculate the hash-based message authentication code (HMAC) value of the string-to-sign by using the HMAC-SHA1 algorithm and encode the HMAC value into a signature string based on Base64 encoding rules. For more information about HMAC, see RFC 2104.

String signature = Base64(HMAC_SHA1(SigningKey, stringToSign))

Important

Set the SigningKey parameter to your AccessKey secret. For more information, see Obtain an AccessKey pair.

Step 5: Add the signature string to the request

After you obtain the signature string, construct the value of the Authorization header based on the following code:

String Authorization = "acs " + AccessKeyId + ":" + signature

Signature example

In this example, the CreateTrigger operation of Alibaba Cloud Container Service for Kubernetes (ACK) is called to create a trigger for an application. Your AccessKey ID is testid, your AccessKey secret is testsecret, the value of the x-acs-signature-nonce header is 15215528852396, and the value of the Date header is Tue 9 Apr 2022 07:35:29 GMT. You can perform the following steps to sign the request:

Construct canonicalized headers.

x-acs-signature-method:HMAC-SHA1
x-acs-signature-nonce:15215528852396
x-acs-signature-version:1.0
x-acs-version:2015-12-15

Construct canonicalized resources.

/clusters/test_cluster_id/triggers

Construct a string-to-sign.

POST
application/json
Gtl/0jNYHf8t9Lq8Xlpaqw==
application/json
Tue 9 Apr 2022 07:35:29 GMT
x-acs-signature-method:HMAC-SHA1
x-acs-signature-nonce:15215528852396
x-acs-signature-version:1.0
x-acs-version:2015-12-15
/clusters/test_cluster_id/triggers

Calculate the signature string.

acs testid:D9uFJAJgLL+dryjBfQK+YeqGtoY=

Add the signature string to the request.

POST /clusters/test_cluster_id/triggers HTTP/1.1
 /* headers */
{
    "accept": "application/json",
    "date": "Tue 9 Apr 2022 07:35:29 GMT",
    "host": "cs.cn-hangzhou.aliyuncs.com",
    "x-acs-signature-nonce": "15215528852396",
    "x-acs-signature-method": "HMAC-SHA1",
    "x-acs-signature-version": "1.0",
    "x-acs-version": "2015-12-15",
    "content-type": "application/json",
    "content-md5": "Gtl/0jNYHf8t9Lq8Xlpaqw==",
    "authorization": "acs testid:D9uFJAJgLL+dryjBfQK+YeqGtoY="
}
/* body */
{
    "project_id": "default/nginx-test",
    "cluster_id": "test_cluster_id",
    "action": "redeploy",
    "type": "deployment"
}

References

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