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
For Amazon.fr (FR)
http://webservices.amazon.fr/onca/xml?Service=AWSECommerceService
For Amazon.ca (CA)
http://webservices.amazon.ca/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
&AWSAccessKeyId=[your Access Key ID here]
&Operation=ItemSearch
&SearchIndex=Books
&Keywords=dog
The parameters in the example are described below:
AWSAccessKeyId is required in all ECS requests. You must sign up for a Access Key ID before you can use ECS by going to aws.amazon.com. Previous to ECS 4.0 version 2007-01-17, requests had to contain a Subscription ID. AWSAccessKeyId and Subscription IDs can still be used in ECS requests. Going forward, however, ECS will only distribute Access Key IDs to new ECS 4.0 developers. For more information, see the section, Access Key ID, below.
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.
Prior to ECS 4.0 version 2005-10-05, every ECS 4.0 request had to have in it a SubscriptionId. Starting with version 2005-10-05, ECS stopped distributing Subscription IDs and started distributing Access Key IDs, which is a new means of identifying the request sender. This twenty-character alphanumeric ID is included in ECS requests using the AWSAccessKeyId parameter. ECS switched to Access Key IDs to support the authentication of requests.
AWSAccessKeyId and SubscriptionId continue to work in ECS 4.0. You can use the value of SubscriptionId as the value for AWSAccessKeyId. You cannot, however, use the value of AWSAccessKeyId as the value for SubscriptionId. Every ECS 4.0 request must include either a SubscriptionId or an AWSAccessKeyId, but not both, for example,
http://webservices.amazon.com/onca/xml ?Service=AWSECommerceService &AWSAccessKeyId=[Your Access Key ID] &Operation=ItemLookup &ItemId=[An ASIN]
Access Key IDs are a forward-looking part of request and user authentication that will be more fully implemented in the future.
If you are new to ECS, you must register to become an ECS 4.0 developer. To register, point your browser at http://aws.amazon.com and click the Register for AWS link. Once you have registered, you will be assigned an Access Key ID.
If you are already an ECS 4.0 developer and have a Subscription ID, you will be assigned an Access Key ID automatically. To view your Access Key ID, point your browser at http://aws.amazon.com and click the Your Web Services Account button and pull down to the View Access Key Identifiers option. Your Access Key ID and Secret Access Key display.
A Secret Access Key is a shared secret between you and Amazon. The key identifies you as a request sender and will be used in the future to authenticate requests. Currently, as an ECS developer, you have no need to use the Secret Access Key. However, you should carefully guard this key. Never put it into an ECS request. Do not use it as the value for your Access Key ID. If you ever suspect that the secrecy of this number has been compromised, Email Amazon immediately at webservices@amazon.com and you will be assigned a new Secret Access Key.
If you include your Access Key ID in the applications you create and distribute, you must maintain a way of contacting your customers in case your Access Key ID changes. It might change, for example, if your Secret Access Key is compromised. An alternative strategy is to require your customers to register with ECS so that they use their own Access Key ID in their requests.
There is never a case in which you should share your Secret Access Key, even in an encrypted form.
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
&AWSAccessKeyId=[Your Access Key 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
&AWSAccessKeyId=[Your Access Key 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.