This section explains how to use REST (Representational State Transfer) to make requests through Amazon E-Commerce Service (ECS). REST is a Web services protocol that was created by Roy Fielding in his Ph.D. thesis (see Architectural Styles and the Design of Network-based Software Architectures for more details about REST).
REST allows you to make calls to ECS by passing parameter keys and values in a URL (Uniform Resource Locator). ECS returns its response in XML (Extensible Markup Language) format. You can experiment with ECS requests and responses using nothing more than a Web browser that is capable of displaying XML documents. Simply enter the REST URL into the browser's address bar, and the browser displays the raw XML response.
Every REST request to ECS begins with a base URL that is specific to the locale in which you want to make the request. The following base URLs are available:
For Amazon.com (US)
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService
For Amazon.co.uk (UK)
http://webservices.amazon.co.uk/onca/xml?Service=AWSECommerceService
For Amazon.de (DE)
http://webservices.amazon.de/onca/xml?Service=AWSECommerceService
For Amazon.co.jp (JP)
http://webservices.amazon.co.jp/onca/xml?Service=AWSECommerceService
The base URL is followed by a series of parameters that define the request. Parameters are separated from the base URL and each other by an ampersand (&) character. Each parameter consists of a key and a value, separated from each other by an equals sign (=). Note that parameters and their values are case-sensitive; for example, Operation=ItemSearch works correctly, but operation=itemsearch produces an error.
The following example shows a simple REST request that searches for books on Amazon.com that are about dogs:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService
&SubscriptionId=[your subscription ID here]
&Operation=ItemSearch
&SearchIndex=Books
&Keywords=dog
The parameters in the example are described below:
SubscriptionId is required in all ECS requests. You must sign up for a subscription ID before you can use ECS.
Operation is required in all ECS requests. The Operation parameter tells ECS what action it should perform. In the example, the operation is ItemSearch, which tells ECS to perform a search for products in the Amazon.com catalog that meet particular criteria.
SearchIndex is required by the ItemSearch operation. SearchIndex tells the ItemSearch operation what type of product to search for. The example searches through the Books index; there are many other search indexes available (see Search Index Values for a complete list of available SearchIndex values).
Keywords tells the ItemSearch operation to search the Amazon.com catalog for specific text values. In the example, the request searches for the word "dog."
You may specify more than one keyword to search for; separate multiple keywords using URL-encoded space characters (%20). For example, to search for cats and dogs, specify Keywords=cats%20dogs in the request. Other non-alphanumeric characters must also be URL-encoded. You may find reference charts for URL encoding at i-Technica and W3 Schools.
You can control how much and what kinds of data are returned in a response by specifying the ResponseGroup parameter. If you omit the ResponseGroup parameter, ECS returns a default set of response groups, depending on the operation you call. Explicitly including one or more response groups in a request refines the output from an operation and allows you to tailor response data to fit the needs of your application.
For example, the ItemSearch request in the previous section returns two default response groups: Request and Small. Here is the same request, this time with the ResponseGroup parameter filled in. This request returns exactly the same response as the first example.
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService
&SubscriptionId=[your subscription ID here]
&Operation=ItemSearch
&SearchIndex=Books
&Keywords=dog
&ResponseGroup=Request,Small
Notice that the values for ResponseGroup are separated by commas, without any spaces. You may specify as many response groups as you wish.
The Request response group simply returns the list of parameters and values you used to make the request. This information is useful in debugging requests. Request is a default response group for every operation.
The Small response group returns global, item-level data about items included in the response. Such data includes the item's Amazon Standard Item Number (ASIN), name, creator (for example, author or artist), product group, URL, and manufacturer. You can expand the information returned by specifying a larger response group, such as Medium or Large. You can also narrow the response to include specific information about each item by specifying response groups like Images or Accessories. See Response Groups for a complete list of available response groups and what data each of them contains.
The following example uses the ItemIds response group to retrieve only the ASINs for books about dogs:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService
&SubscriptionId=[your subscription ID here]
&Operation=ItemSearch
&SearchIndex=Books
&Keywords=dog
&ResponseGroup=ItemIds
Note that the data returned by a response group is dependent on the operation that is being called. For example, the ItemIds response group returns only an item ID when used with the ItemLookup operation, but it returns both item IDs and the total number of items found if used with the ItemSearch operation.