Using Query API

Query requests are either HTTP or HTTPS requests that use the HTTP verbs GET or POST, and a Query parameter named as Action or Operation. Action will be used throughout this section. Operation is compatible with other AWS Query APIs.

Making Query Requests

This section will teach you about query requests through the following topics:

• Query Parameters
• Request ID
• Request Authentication
• Query Example

Query Parameters

Each and every query request has to include some common parameters, which help in handling selecting and authenticating an action.

Note: Some API operations take many lists of parameters. These lists are specified by using the following notation: param.member.n. Values of n integers starting from 1. All lists have to follow this notation, including lists that contain only one parameter. For ex: A Query parameter list resembles this:

&attribute.member.1=this
&attribute.member.2=that

Request ID

In each and every response from AWS, you will see the element ResponseMetadata, containing a string element called RequestId. This is nothing but a unique identifier assigned by AWS to a request for troubleshooting and tracking purposes.

Request Authentication

Regardless of whether you use the HTTP or HTTPS protocol to send to send query requests, you have to include a signature in every request. The following steps instruct on how to create the signature:

• Firstly, you need to create a canonicalized query string that you will need later in this procedure:

◦    You need to sort out the UTF-8 query string components by parameter name with natural byte ordering. The parameters can come from the GET URL, or from the POST body (when Content-Type is application/x-www-form-urlencoded).

◦    URL-encode the parameter name and values, following these rules:

• Don’t URL-encode any unreserved characters that RFC 3986 defines.
• Percent-encode all other characters with %XY, where X and Y are hex characters 0-9, and/or uppercase A-F.
• Percent-encode extended UTF-8 characters in the form %XY%ZA.
• Percent-encode the space character as %20 (not as + like common encoding schemes do).
• Separate the encoded parameter names from their encoded values with the = sign (ASCII character 61), disregarding if the parameter value is empty.
• Separate the name-value pairs with an ampersand (&) (ASCII character 38).

Note: Currently, you don’t need to encode AWS service parameter names, as all of them use unreserved characters. However, you can include a code to handle parameter names that use reserved characters, for possible future use.

• Create the following string to sign according to the following pseudo-grammar (the ”\n” represents an ASCII newline).

StringToSign = HTTPVerb + “\n” +
ValueOfHostHeaderInLowercase + “\n” +
HTTPRequestURI + “\n” +
CanonicalizedQueryString <from the preceding step>

The HTTPRequestURI component is the HTTP absolute path component of the URI up to, but not including the query string. If the HTTPRequestURI is empty, use a forward slash (/).

• Now you need to calculate an RFC 2104-compliant HMAC with the string you have just created. Your Secret Access Key will serve as the key, and SHA256 or SHA1 as the hash algorithm. For further information, please visit http://www.ietf.org/rfc/rfc2104.txt.
•  You should now convert the resulting value to base64.
•  Use the resulting value as the value of the Signature request parameter.

Important Note: Your final signature, which you send in the request, has to be URL-encoded as per RFC 3986 specifications (For any further information regarding this, please visit http://www.ietf.org/rfc/rfc3986.txt). If your toolkit URL-encodes your final request, then it handles the required URL-encoding of the signature. However, if your toolkit doesn’t URL-encode the final request, then you have to URL-encode the signature prior to including it in the request. Most importantly, you should make sure that the signature is URL-encoded only once. (A common mistake many user make, is to URL-encode it manually during signature formation, and again when the toolkit URL-encodes the entire request).

Query Example

Following is an example that describes an Auto-Scaling group API request (This example uses CreateAutoScalingGroup):

http://autoscaling.amazonaws.com/?AutoScalingGroupName=webtier
&LaunchConfigurationName=wt20080929
&MinSize=0
&MaxSize=2
&DefaultCooldown=0
&Expires=2011-02-10T12%3A00%3A00Z
&AvailabilityZones.member.1=us-east-1c
&Action=CreateAutoScalingGroup
&Version=2011-01-01
&SignatureVersion=2
&SignatureMethod=HmacSHA256
&AWSAccessKeyId=<Your AWS Access Key ID>

The following string is the one to sign:

GET\n

autoscaling.amazonaws.com\n
/\n
AWSAccessKeyId=<Your AWS Access Key ID>
&Action=CreateAutoScalingGroup
&AutoScalingGroupName=webtier
&AvailabilityZones.member.1=us-east-1c
&DefaultCooldown=0
&Expires=2011-02-10T12%3A00%3A00Z
&LaunchConfigurationName=wt20080929
&MinSize=0
&MaxSize=2
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Version=2011-01-01
The following is the signed request: http://autoscaling.amazonaws.com/?AutoScalingGroupName=webtier

&LaunchConfigurationName=wt20080929
&MinSize=0
&MaxSize=2
&DefaultCooldown=0
&AvailabilityZones.member.1=us-east-1c
&Action=CreateAutoScalingGroup
&Version=2011-01-01
&SignatureVersion=2
&SignatureMethod=HmacSHA256
&AWSAccessKeyId=<Your AWS Access Key ID>
&Signature=<URLEncode(Base64Encode(Signature))>
&Expires=2011-02-10T12%3A00%3A00Z