API request protocol - Simple Message Queue (formerly MNS)

This document describes the request structure, common parameters, response, and the request signature method for HTTP API calls to Simple Message Queue (SMQ, formerly MNS).

Request structure

Endpoint

Simple Message Queue (SMQ, formerly MNS) is available in multiple regions. Each region provides a public endpoint and an internal endpoint. For more information, see Regions and endpoints.

Request method

You can send requests to Simple Message Queue (SMQ, formerly MNS) over HTTP by using methods such as PUT, POST, GET, and DELETE.

Requests must include the correct parameters, headers, and body. Both requests and responses are encoded in UTF-8.

Common parameters

Common request headers

Parameter	Required	Description
Authorization	Yes	The authentication string. For more information, see Request signature method.
Content-Length	Yes	The length of the HTTP request body.
Content-Type	Yes	The MIME type of the request content. Currently, only text and XML formats are supported.
Content-MD5	No	The MD5 hash of the HTTP request body. For more information, see The Content-MD5 Header Field. Note The `Content-MD5` header is optional. Most API operations, such as `SendMessage` and `ReceiveMessage`, do not require this header. If you do not set the `Content-MD5` header, use an empty string for the `CONTENT-MD5` field when you construct the string-to-sign.
Date	Yes	The time when the request is created. The time must be in GMT format. If the time difference between the request and the SMQ server time exceeds 15 minutes, the request is considered invalid.
Host	Required for HTTP/1.1. Optional for HTTP/1.0.	The request endpoint. The format is `$AccountId.mns.cn-hangzhou.aliyuncs.com`. Obtain your AccountId from the Alibaba Cloud website. Find the appropriate SMQ endpoint for your region in the API documentation.
x-mns-version	Yes	The version of the SMQ API to use. The current version is `2015-06-06`.
x-mns-date	No	An alternative to the `Date` header. Use this header if your client or browser environment prevents you from setting the standard `Date` header.

Common response headers

Parameter	Description
Content-Length	The length of the HTTP response body.
Connection	The status of the HTTP connection.
Date	The time the response was generated, in GMT format.
Server	The name of the SMQ server that handled the request.
x-mns-request-id	A unique ID for the request.
x-mns-version	The version of the SMQ API. The current version is `2015-06-06`.

Response

API calls return data in a standardized format. An HTTP status code in the 2xx range indicates a successful call. A status code in the 4xx or 5xx range indicates failure. Successful responses are in XML format.

The XML response includes success information and specific business data. The following example shows the basic structure:

    <?xml version="1.0" encoding="utf-8"?> 
    <!--Root node of the result--> 
    <RootNode xmlns="http://mns.aliyuncs.com/doc/v1/">
    <!--Returned child node-->
    </RootNode>

If an API call fails, no result data is returned. Instead, the service returns an HTTP 4xx or 5xx status code. The response body contains a specific error code and message. It also includes a globally unique request ID (RequestId) and the host ID (HostId) of the server that handled your request.

For detailed error information, see Error codes.

Request signature method

Overview

The Simple Message Queue (SMQ, formerly MNS) service authenticates every request. Each request that you send to SMQ must include a signature in its header. The SMQ SDKs automatically complete the signing process. We recommend that you use an SDK to send requests to avoid the manual signing process.

The signing process consists of the following steps:

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

Step 1: Construct the string-to-sign

Use the following pseudo-code to construct the string-to-sign:

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

Parameter	Description
HttpMethod	The HTTP request method in uppercase. Examples: `PUT`, `GET`, `POST`, `DELETE`.
Content-Md5	The MD5 hash of the request body. This is optional. If the `Content-MD5` header is not included in the request, use an empty string here.
CONTENT-TYPE	The content type of the request body. If the `Content-Type` header is not included in the request, use an empty string here.
DATE	The date and time of the request. The format is: `Thu, 07 Mar 2012 18:49:58 GMT`. If you use `x-mns-date` to replace DATE, DATE cannot be left empty and must be set to the value of `x-mns-date`. This field cannot be empty. Only the GMT format is supported. If the time difference between the request and the Simple Message Queue (SMQ, formerly MNS) server time exceeds 15 minutes, the service considers the request invalid and returns a `400` error code. For more information, see Error codes.
CanonicalizedMNSHeaders	The concatenation of all HTTP headers that start with the `x-mns-` prefix. These headers must be processed as follows: The header keys must be converted to lowercase. The headers must be sorted alphabetically by key. Concatenate the headers as shown in the following pseudo-code. `// Original request headers Map<String, String> httpHeaders = request.getHeaders(); // Sort keys and convert to lowercase sortHeadersKeyAndToLowerCase(httpHeaders); // Concatenate 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 URI of the HTTP requested resource is the part of the HTTP endpoint address specified in the subscription configuration, excluding the domain name and port. For example, if the configured endpoint address is `http://123.123.XX.XX:8080/api/test?code=200`, the URI is `/api/test?code=200`. If the endpoint address is `http://www.aliyun.com/mns/help`, the URI is `/mns/help`. Important If your system includes a gateway or other proxy, the URI at the verification point might differ from the one in your subscription configuration. In this case, you must use the URI from the subscription configuration.

Step 2: Calculate the signature

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

The parameters are described as follows:

Parameter	Description
Base64	The Base64 encoding method.
HMAC-SHA1	The signing algorithm. SMQ uses the `HMAC-SHA1` method defined in RFC 2104.
AccessKey secret	Your AccessKey secret. It corresponds to the AccessKey ID used in the signature.
UTF-8-Encoding-Of	The UTF-8 encoding format.
StringToSign	The string-to-sign constructed in Step 1: Construct the string-to-sign.

Step 3: Add the signature to the request

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

The key is the constant string Authorization. The value is a string that is constructed by concatenating the AccessKeyId and Signature variables in the format MNS ${accessKeyId}:${Signature}. In this format, Signature is the custom-built signature by Simple Message Queue (SMQ, formerly MNS), which is the value generated in Step 2: Calculate the signature (Signature).

Signature examples

The following is a 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>

The following are sample responses:

Example 1

The service returns a 403 Forbidden error if the provided AccessKey ID does not exist or is inactive.

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>

Example 2

The service returns a 403 Forbidden error if the Date header is missing or has an invalid format.

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>

Example 3

Requests must arrive at the Simple Message Queue (SMQ, formerly MNS) server within 15 minutes of their timestamp. Otherwise, the service returns a 408 Request Timeout error.

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>