 | Feedback |  |
The Amazon Associates Web Service web service supports REST requests for remotely calling Amazon Associates Web Service operations hosted by Amazon servers. REST requests are simple HTTP requests, using either the GET method with parameters in the URL, or the POST method with parameters in the POST body. The response is an XML document that conforms to a schema.
You might use REST requests because they are more intuitive than their SOAP counterpart or because a SOAP toolkit is not available for your platform. The example requests used throughout this guide are in REST.
Topics
Amazon Associates Web Service REST requests are URLs, for example,
http://ecs.amazonaws.com/onca/xml?Service=AWSECommerceService&Operation=ItemSearch&AWSAccessKeyId=[Access Key D]& AssociateTag=[ID]&SearchIndex=Apparel&Keywords=Shirt
If you substituted real IDs in this request and put the entire example in a browser, you would be sending Amazon Associates Web Service a request.
Although the example above is in the form you'd enter the request into a browser, it is difficult to read. For that reason, this guide would present the same request as follows:
http://ecs.amazonaws.com/onca/xml? Service=AWSECommerceService& Operation=ItemSearch& AWSAccessKeyId=[Access Key ID]& AssociateTag=[ID]& SearchIndex=Apparel& Keywords=Shirt
Part of every Amazon Associates Web Service request is the same, the other part of the request changes according to the parameters used in the request, as shown in the following figure.
The first two lines in the above example contain the endpoint, http://ecs.amazonaws.com/onca/xml, and the service name, AWSECommerceService.
Amazon hosts many web services in addition to Amazon Associates Web Service, including Mechanical Turk and S3. The service name in the request specifies that the request should be sent by the web servers to Amazon Associates Web Service. This line is always the same in every Amazon Associates Web Service request, regardless of locale:
Service=AWSECommerceService&
The endpoint value varies by locale but there are only two endpoints per locale. One endpoint in a locale is the secure version of the other endpoint. The following table lists the endpoints to use in Amazon Associates Web Service requests.
| Locale | Endpoint |
|---|---|
| CA |
http://ecs.amazonaws.ca/onca/xml https://ecs.amazonaws.ca/onca/xml |
| DE |
http://ecs.amazonaws.de/onca/xml https://ecs.amazonaws.de/onca/xml |
| FR |
http://ecs.amazonaws.fr/onca/xml https://ecs.amazonaws.fr/onca/xml |
| JP |
http://ecs.amazonaws.jp/onca/xml https://ecs.amazonaws.jp/onca/xml |
| UK |
http://ecs.amazonaws.co.uk/onca/xml https://ecs.amazonaws.co.uk/onca/xml |
| US |
http://ecs.amazonaws.com/onca/xml https://ecs.amazonaws.com/onca/xml |
The endpoint remains the same for all Amazon Associates Web Service requests, for example:
http://ecs.amazonaws.com/onca/xml
The remaining terms in the request vary significantly according to the operation chosen. The terms, however, follow a pattern, as shown in the next figure.
The first two lines identify the request submitter. The first line is required; every request must contain an AWS Access Key ID, which identifies the submitter. You receive an AWS Access Key ID when you sign up with Amazon Associates Web Service.
The second identifier, AssociateTag, is optional. It is an ID for an Associate. If you are an Associate, you must include your Associate tag in the request to receive a referral fee for a customer's purchase.
The Operation parameter is required. Its value is one of the Amazon Associates Web Service operations. These operations are described throughout this guide and in the Amazon Associates Web Service API Reference Guide.
The last lines, operation parameters, are representative of parameters that the operation requires, and optional parameters that the operation can use. Requests can contain zero or more operation (up to ten) parameters. These parameters are described in the discussion of each operation in the Amazon Associates Web Service API Reference Guide.
A special parameter that is optional for all Amazon Associates Web Service operations is ResponseGroup. Response groups control the kind of information returned by the request. For example, the Large response group returns a great deal of information about the items included in a response, whereas the Medium and Small response groups return less.
Besides these generic response groups, there are very specific ones. For example, if you want to return images of the items included in a response, you would include the Image response group in the request. If you wanted pricing information, you would include the Offer response group in the request. To get browsenode information, you'd include the BrowseNode response group. The specificity of the response groups enables you to return only the information you want.
Each Amazon Associates Web Service operation can only work with a subset of all Amazon Associates Web Service response groups. The valid response groups that each Amazon Associates Web Service operation can use is listed in the Amazon Associates Web Service API Reference Guide.
All Amazon Associates Web Service operations use some response group by default. So, specifying additional response groups is optional. Every Amazon Associates Web Service operation uses the Request response group, which echoes operation name and the input parameters sent in the request. The other response groups used by default vary by the operation. For example, CartCreate, CartAdd, and CartModify use, by default, the Cart response group, which provides detailed information about the items in a cart. The API Reference Guide lists the default response groups used by each operation.
Now, when you read requests in this guide, your eye should jump to the Operation parameter and all of the required and optional parameters associated with the specified Amazon Associates Web Service operation.
Some Amazon Associates Web Service operations have many parameters and, as you will learn in a future section, you can combine multiple single requests in one, longer batch request. The upper limit is bounded by the maximum number of characters that can be in a request. The maximum number differs by browser. For example, the limit for a URL in Microsoft's Internet Explorer is a little more than 2000 characters. It would be unusual to have a request that approached this upper boundary.
One of the values of using REST is that its syntax is simple, which makes REST requests easy to read. This section summarizes all of the REST syntax rules that you must keep in mind when creating a REST request.
Because a REST request is a URL, there can be no spaces between the parts of a request. A browser will stop reading when it runs across the first space. For example, if the last parameter read,
Keywords=Blue Shirts
the request would end on "Blue." "Shirts" would never be read. If you have key words, such as names, that do have spaces in them, you must URL-encode the space using %20. For the above example to work, you would include a URL-encoded space, as follows.
Keywords=Blue%20Shirts
The same problem occurs if you put spaces between the parameters in a request, for example,
SearchIndex=Apparel& Keywords=Shirt
In this example, the request would end with "Apparel&." Often, this kind of mistake returns an error because parameters required by the operation are not read. So, make sure to remove all spaces within a request.
The question mark (?) and ampersand (&) separate the terms in a REST request. The first term in the request must always be the endpoint, which, in the example above, is,http://ecs.amazonaws.com/onca/xml. A question mark always follows the endpoint. The question mark tells the Amazon Associates Web Service web servers to start parsing the request for parameters.
Ampersands separate all of the other parameter name-value pairs in the request. The order of the parameter name-value pairs is inconsequential, as long as they all occur after the question mark.
Request parameter values are set using the format:
ParameterName=value
For example,
Operation=ItemSearch
Parameter values must be URL-encoded. There are some characters, such as an asterisk or space, that cannot go into a URL. There are equivalents of these characters that you use in requests instead. For example, the URL encoded equivalent of a space is %20. So, instead of writing:
Name=John Smith
you would write:
Name=John%20Smith
Parameter names and values are case sensitive. For example,
SearchIndex=Apparel
is fine. The following examples return errors because the capitalization is incorrect.
Searchindex=Apparel SearchIndex=apparel
As you can see in these examples, parameter names and values start with capitals. If the name or value is a compound word, the beginning of each new word is capitalized, for example, in the parameter name, SearchIndex, the "I" is capitalized.
The vast majority of parameters can be specified in a REST request using just the name of the parameter and an appropriate value, with the value URL-encoded to make the request a valid URL, for example,
Author=Steve%20Davenport
Some parameters, however, can be repeated in a request. In that case, the parameter names are differentiated by adding a period (.) after the parameter name and then a sequence number, for example:
Item.1=1234& Item.2=2345
Other parameters can be repeated but, in addition, have associated parameters. These parameters extend the above example by adding another period and the associated parameter name, for example,
Item.1.ASIN=3456789123& Item.1.Quantity=2
In this example, the item being added to a shopping cart has an identifier, the ASIN, and a quantity value. The equivalent expression in an XML document is:
<Item> <ASIN>3456789123</ASIN> <Quantity>2</Quantity> </Item>
The sequence number associates the identifier and its quantity value. The following example shows two compound parameters.
Item.1.ASIN=3456789123& Item.1.Quantity=2& Item.2.ASIN=123456& Item.2.Quantity=1
The sequence numbers associate the ASIN and quantity values. This means that the compound parameters can be written in a different order without causing a problem.
Item.1.ASIN=3456789123& Item.2.ASIN=123456& Item.1.Quantity=2& Item.2.Quantity=1
