API request protocol - Simple Message Queue (formerly MNS)

This topic describes the request syntax, common parameters, response, and signature authentication method when you call the Simple Message Queue (SMQ, formerly MNS) API over HTTP.

Request syntax

Regions and endpoints

SMQ supports multiple regions. In each region, a public endpoint and an internal endpoint are provided. For more information, see Regions and endpoints.

Request methods

SMQ allows you to send requests over HTTP. SMQ supports HTTP methods such as PUT, POST, GET, and DELETE to send requests.

When you send a request, make sure that the request parameters, request headers, and request body are valid. The request and the response are encoded in UTF-8.

Common parameters

Common request headers

Header	Required	Description
Authorization	Yes	The string that is used for authentication. For more information, see Sign requests.
Content-Length	Yes	The size of the message body in the request.
Content-Type	Yes	The Multipurpose Internet Mail Extensions (MIME) type of the message body. Valid values: text and xml.
Content-MD5	No	The MD5 hash value of the message body. For more information, see The Content-MD5 Header Field.
Date	Yes	The time when the request is generated. The time must be in GMT. If the interval between the time when the request is generated and the time when the request is received exceeds 15 minutes, SMQ determines that the request is invalid.
Host	This parameter is required if you use HTTP/1.1 and is optional if you use HTTP/1.0.	The SMQ server that receives the request. Set the value in the following format: `$AccountId.mns.cn-hangzhou.aliyuncs.com`. AccountId indicates your Alibaba Cloud account ID. You can obtain the Alibaba Cloud account ID from the Alibaba Cloud Management Console.
x-mns-version	Yes	The version of the API to be used. The latest API version is 2015-06-06.
x-mns-date	No	This header can be used to replace the Date header. If your browser does not support the Date header, you can use the x-mns-date header instead.

Common response headers

Header	Description
Content-Length	The size of the message body that is returned.
Connection	The status of the HTTP connection.
Date	The time when the response is returned. The time is displayed in GMT.
Server	The name of the SMQ server that responds to the request.
x-mns-request-id	The request ID.
x-mns-version	The version of the API that is used. The latest API version is 2015-06-06.

Response

All responses are returned in a unified format. A returned HTTP status code of 2xx indicates that the request is successful. A returned HTTP status code of 4xx or 5xx indicates that the request failed. Success responses are in the XML format.

Responses in the XML format include the result of the request and the details of the operation. Example:

    <?xml version="1.0" encoding="utf-8"?> 
    <!--Result root node--> 
    <Root node xmlns="http://mns.aliyuncs.com/doc/v1/">
    <!—Returned child node-->
    </Root node>

If an error occurs when you call an API operation, no data is returned and a 4xx or 5xx HTTP status code is returned for the HTTP request. The response body contains the specific error code and error message. The response body also contains the request ID and ID of the host that you want to access with this request. The request ID is globally unique.

For more information about error messages, see Error codes.

Request signature method

Overview

SMQ verifies each API request to ensure data security. Therefore, each request that is sent to SMQ must contain a signature in the Authorization header. SMQ SDKs have implemented automatic signature. We recommend that you use SDKs to send API requests so that you do not need to manually sign requests.

The following steps are involved in signing a request:

Step 1: Construct a string-to-sign
Step 2: Calculate the signature string
Step 3: Add the signature string to the request

Step 1: Construct a string-to-sign

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

StringToSign = HttpMethod + "\n" 
         + CONTENT-MD5 + "\n"     
         + CONTENT-TYPE + "\n" 
         + DATE + "\n" 
         + CanonicalizedMNSHeaders
         + CanonicalizedResource;

Parameter	Description
HttpMethod	The HTTP method in uppercase letters, such as PUT, GET, POST, or DELETE.
Content-MD5	The MD5 hash value of the request body. If the Content-MD5 header is not specified, leave this parameter empty.
CONTENT-TYPE	The type of the request body. If the Content-Type header is not specified, leave this parameter empty.
DATE	The time when the request was sent. Example: `Thu, 07 Mar 2012 18:49:58 GMT`. If you use the `x-mns-date` header instead of the Date header, set this parameter to the value of `x-mns-date` header. This parameter is required and the value must be in the GMT format. If SMQ does not receive a request within 15 minutes after the request is sent, SMQ considers the request is invalid and returns the error code 400. For more information, see Error codes.
CanonicalizedMNSHeaders	The combination of HTTP headers that are prefixed by `x-mns-`. The value of this parameter must meet the following requirements: The header names must be in lowercase. The headers must be sorted in alphabetical order. The headers are concatenated. `// The original request headers. Map<String, String> httpHeaders = request.getHeaders(); // Sort the headers and convert the headers to lowercase. sortHeadersKeyAndToLowerCase(httpHeaders); // Concatenate the headers. Set<String> keySet = httpHeaders.keySet(); for (String key : keySet) { if (key.startsWith("x-mns-")) { CanonicalizedMNSHeaders.append(key).append(":") .append(httpHeaders.get(key)).append("\n"); } }`
CanonicalizedResource	The Uniform Resource Identifier (URI) of the resource requested by the HTTP request. You can obtain a URI by deleting the domain name and port number from the IP address of an HTTP server that responds to the request. For example, if you use the endpoint `http://123.123.XX.XX:8080/api/test?code=200`, the URI is `/api/test?code=200`; The URI is `/mns/help` for `http://www.aliyun.com/mns/help`. Important In a scenario where gateways or other transit gateways are configured in your system, the URI of the resource requested by the HTTP request shall prevail if it is not same as the URI of the API requests that are verified by SMQ.

Step 2: Calculate the signature string

Signature = Base64( HMAC-SHA1( ${AccessSecret}, UTF-8-Encoding-Of(${StringToSign})) )

The following table describes the parameters.

Parameter	Description
Base64	The Base64 encoding method.
HMAC-SHA1	The algorithm for signature calculation. The `HMAC-SHA1` algorithm defined in RFC 2104 is used to calculate the signature.
AccessSecret	The AccessKey secret corresponds to the AccessKey ID in the Authorization header.
UTF-8-Encoding-Of	The UTF-8 encoding method.
StringToSign	The string-to-sign obtained in Step 1: Construct a string-to-sign.

Step 3: Add the signature string to the request

addHeader("Authorization","MNS " +  ${AccessKeyId}+ ":" + ${Signature})

The value of the Authorization header is in the MNS ${accessKeyId}:${Signature} format. accessKeyId indicates the AccessKey ID. ${Signature} indicates the signature string obtained in Step 2: Calculate the signature string.

Signature example

Sample request:

PUT /queues/$queueName?metaOverride=true HTTP/1.1
Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
Date: Wed, 08 Mar 2012 12:00:00 GMT
Authorization: MNS 15B4D3461F177624****:xQE0diMbL****f3YB+FIEXAMPLE=

<?xml version="1.0" encoding="UTF-8"  ?>
<Queue xmlns="http://mns.aliyuncs.com/doc/v1/">
<VisibilityTimeout >60</VisibilityTimeout>
<MaximumMessageSize>1024</MaximumMessageSize>
<MessageRetentionPeriod>120</MessageRetentionPeriod>
<DelaySeconds>30</DelaySeconds>
</Queue>

Sample responses:

Sample response 1

If the AccessKey ID does not exist or is in the Disabled state, the 403 error code is returned.

Content-Type: text/xml
Content-Length: 314
Date: Wed, 18Mar 2012 08:04:06 GMT
x-mns-request-id: 512B2A634403E52B1956****

<?xml version="1.0" encoding="utf-8"?>
<Error xmlns="http://mns.aliyuncs.com/doc/v1/">
<Code>AccessIDAuthError</Code>
<Message>
    AccessID authentication fail, please check your AccessID and retry.
</Message>
<RequestId>512B2A634403E52B1956****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>

Sample response 2

If the Date header is not specified or the value of the Date header is invalid, the 403 error code is returned.

Content-Type: text/xml
Content-Length: 274
Date: Wed, 18Mar 2012 08:04:06 GMT
x-mns-request-id: 512B2A634403E52B1956****

<?xml version="1.0" encoding="UTF-8"?>
<Error xmlns="http://mns.aliyuncs.com/doc/v1/">
<Code>InvalidArgument</Code>
<Message>Date Header is invalid or missing.</Message>
<RequestId>7E1A5CF258F535884403****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>

Sample response 3

If SMQ does not receive a request within 15 minutes after the request is sent, the 408 error code is returned.

Content-Type: text/xml
Content-Length: 283
Date: Wed, 11 May 2011 09:01:51 GMT
x-mns-request-id: 512B2A634403E52B1956****

<?xml version="1.0"  encoding="UTF-8"?>
<Error xmlns="http://mns.aliyuncs.com/doc/v1/">
<Code>TimeExpired</Code>
<Message>
        The http request you sent is expired.
</Message>
<RequestId>512B2A634403E52B1956****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>