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 are sending Product Advertising API a request.
Although the previous example is the form you 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 example AWS access identifiers, see Example REST Requests.
General Request Format
Request Terms that Remain the Same
The first two lines in the preceding example have the following:
The endpoint, http://webservices.amazon.com/onca/xml.
The service name, AWSECommerceService.
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 for 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 AWS access key ID is required. It identifies the request submitter. You receive an AWS access key ID when you register for Product Advertising API.
AssociateTag is required. This is the ID for your Associate account. 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 for each operation. The terms, however, follow a pattern, as shown in the next figure.
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 required and optional parameters. Requests can contain zero or more operation (up to ten) parameters.
An optional parameter for all Product Advertising API operations is
ResponseGroup. Response groups control the type 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.
There are response groups that return specific item information. For example, if you
want to return images of the items, include the
group in the request. If you want price information, include the
Offer response group
in the request. To get browse node information, include the
BrowseNode response group.
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 API Reference.
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.
CartModify use, by default, the
Cart response group, which provides detailed information about the items in a cart.
When you see request examples in this guide, note the
Operation parameter and all of the required and optional parameters.