All Products
Search
Document Center

:ROA style

Last Updated:Nov 04, 2023

Overview

This topic describes how 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.

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.

cs.aliyuncs.com

resource_URI_parameters

Yes

The resource uniform resource identifier (URI) parameters, including the identifiers of the resources that you want to access and the request parameters of the operation.

/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 for 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 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

Request structure

A complete API request consists of the following parts:

HTTPMethod /resource_URI_parameters
RequestHeader
RequestBody

Request parameters consist of 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 a 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" /* 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 response:

{
    "code": "400", /* Error Code */
    "message": "Cluster permission denied", /* Error Message */
    "requestId": "A026BC61-0523-5A6D-A5F3-314A3D92FD50", /* Request ID */
    "status": 400 /* HTTP Status Code */
}

If an API call fails, you can troubleshoot the error on the Alibaba Cloud OpenAPI Diagnostics 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

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

  • Convert all HTTP header field 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 preceding 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, and concatenate all the headers.

Step 2: Construct canonicalized resources

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

  1. Sort the parameters in the request query string by name in alphabetical order, and concatenate the parameters by using an ampersand (&) to generate the sorted query string.

  2. Concatenate the requested resource path with the sorted query string by using a question mark (?) to obtain canonicalized resources. The requested resource path refers to 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 requested resource path as the canonicalized resource.

Examples

Original request URL:

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

Canonicalized resources:

/instances?group=test_group&status=ONLINE

Step 3: Create a string-to-sign

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

CanonicalizedResource

The canonicalized resources that are obtained from Step 2: Construct canonicalized resources.

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 value of 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:

  1. 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
  1. Construct canonicalized resources.

/clusters/test_cluster_id/triggers
  1. 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
  1. Calculate the signature string.

acs testid:D9uFJAJgLL+dryjBfQK+YeqGtoY=
  1. 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"
}