Anatomy of a REST Request
Product Advertising API REST requests are URLs, as shown in the following example.
[Access Key ID]&AssociateTag=
[ID]&SearchIndex=Apparel& Keywords=Shirt&Timestamp=[YYYY-MM-DDThh:mm:ssZ]&Signature=[Request Signature]
If you substituted real IDs in this request and put the entire example in a browser, you would be sending Product Advertising API a request.
Although the preceding example is in the form you would enter in a browser, it is difficult to read. For this reason, this guide presents the same request as follows.
http://webservices.amazon.com/onca/xml? Service=AWSECommerceService& Operation=ItemSearch& AWSAccessKeyId=
[Access Key ID]& AssociateTag=
[ID]& SearchIndex=Apparel& Keywords=Shirt &Timestamp=[YYYY-MM-DDThh:mm:ssZ] &Signature=[Request Signature]
For more information about
Signature, see Authentication Parameters.
For information about signing a request using sample AWS access identifiers, see Example REST Requests.
General Request Format
Request Terms that Remain the Same
The first two lines in the preceding example contain the endpoint, http://webservices.amazon.com/onca/xml, and the service name, AWSECommerceService.
Amazon hosts many web services in addition to Product Advertising API, including Amazon Mechanical Turk and Amazon Simple Storage Service (Amazon S3). The service name in the request specifies that the request should be sent by the web servers to Product Advertising API. This line is always the same in every Product Advertising API request, regardless of locale.
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 Product Advertising API requests.
The endpoint remains the same for all Product Advertising API requests, as shown in the following example.
The third and fourth lines identify the request submitter. The AWSAccessKey Id is required; it helps identify the request submitter. You receive an AWS Access Key ID when you sign up with Product Advertising API.
The other identifier, AssociateTag, is required. It is an ID for an Associate. If you are an Associate, you must include your Associate tag in each request to be eligible 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 the next figure.
The Operation parameter is required. Its value is one of the Product Advertising API operations. These operations are described throughout this 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 Product Advertising API Reference Guide.
A special parameter that is optional for all Product Advertising API 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 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 browse node information, you'd include the BrowseNode response group. The specificity of the response groups enables you to return only the information you want.
Each Product Advertising API operation can work with only a subset of all Product Advertising API response groups. The valid response groups that each Product Advertising API operation can use are listed in the Product Advertising API Reference Guide.
All Product Advertising API operations use some response group by default. So specifying additional
response groups is optional. Every Product Advertising API operation uses the Request response group, which
echoes the operation name and the input parameters sent in the request. The other response groups used
by default vary by operation. For example,
CartModify use, by default, the Cart
response group, which provides detailed information about the items in a cart. The API Reference
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 Product Advertising API operation.