Blog

Tutorial: Amazon.com Search API

Posted on
Anatomy of a REST Request

Anatomy of a REST Request Figure 7 Anatomy of a REST Request Parameters of a REST Request Figure 8 Parameters of a REST RequestAmazon employs a Representational State Transfer or RESTful architecture in the deployment of its web services. RESTful services usually have addressable resources and employ a well-defined and uniform structure in the syntax used for access to their resources. In this tutorial, REST requests will be used to access the Amazon Associates Web Service. These requests are URLs, as shown in the following example.

http://ecs.amazonaws.com/onca/xml?Service=AWSECommerceService&Operation=ItemSearch
&AWSAccessKeyId=[Access Key ID]&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 preceding example 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

General Request Format

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 Figure 7.

Request Terms that Remain the Same

The first two lines in the preceding example contain the endpoint, http://ecs.amazonaws.com/onca/xml, and the service name, AWSECommerceService. The third and fourth lines identify the request submitter. The AWSAcessKey Id is required; it helps identify the request submitter. You receive an AWS Access Key ID when you sign upwith Amazon Associates Web Service. Also included in every request is a signature. This is an SHA-1 encrypted value created using the developer’s Secret Access Key, which given to every developer once they sign up to become an Associate. Because the AWS Access Key ID is sent in the clear, it cannot be used as the sole identity for authenticating the request. Instead, the AWS Access Key ID is used by the Amazon Associates Web Service to look up the Secret Access Key associated with it. If that value matches the one encrypted in the request’s signature parameter, the request is processed. The other identifier, AssociateTag, is optional. It is an ID for an Associate. If you are an Associate, you must include your Associate tag in each request to receive a referral fee for a customer’s purchase.

Request Terms that Change

The remaining terms in the request vary significantly according to the operation chosen. The terms, however, follow a pattern, as shown in Figure 8. The Operation parameter is required. Its value is one of the Amazon Associates Web Service operations. These operations are described 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.