Product Advertising API
Developer Guide (API Version 2013-08-01)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

Anatomy of a REST Request

Product Advertising API REST requests are URLs, as shown in the following example.

http://webservices.amazon.com/onca/xml?Service=AWSECommerceService&Operation=ItemSearch&
AWSAccessKeyId=[Access Key D]&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 Timestamp and Signature, see Authentication Parameters.

For information about signing a request using sample AWS access identifiers, see Example REST Requests.

General Request Format

Part of every Product Advertising API request is always the same. The other part of the request varies according to the parameters used in the request, as shown in the following figure.

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.

Service=AWSECommerceService&

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.

LocaleEndpoint
BR

http://webservices.amazon.com.br/onca/xml

https://webservices.amazon.com.br/onca/xml

CA

http://webservices.amazon.ca/onca/xml

https://webservices.amazon.ca/onca/xml

CN

http://webservices.amazon.cn/onca/xml

https://webservices.amazon.cn/onca/xml

DE

http://webservices.amazon.de/onca/xml

https://webservices.amazon.de/onca/xml

ES

http://webservices.amazon.es/onca/xml

https://webservices.amazon.es/onca/xml

FR

http://webservices.amazon.fr/onca/xml

https://webservices.amazon.fr/onca/xml

IN

http://webservices.amazon.in/onca/xml

https://webservices.amazon.in/onca/xml

IT

http://webservices.amazon.it/onca/xml

https://webservices.amazon.it/onca/xml

JP

http://webservices.amazon.co.jp/onca/xml

https://webservices.amazon.co.jp/onca/xml

UK

http://webservices.amazon.co.uk/onca/xml

https://webservices.amazon.co.uk/onca/xml

US

http://webservices.amazon.com/onca/xml

https://webservices.amazon.com/onca/xml

The endpoint remains the same for all Product Advertising API requests, as shown in the following example.

http://webservices.amazon.com/onca/xml

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.

Response Groups

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, CartCreate, CartAdd, and 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.