Anatomy of a REST Request

Product Advertising API: 2009-11-01

previous page next page

Anatomy of a REST Request

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

http://ecs.amazonaws.com/onca/xml?Service=AWSECommerceService&Operation=ItemSearch&
AWSAccessKeyId=[Access Key D]&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 Product Advertising API 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 Product Advertising API request is the same, the other part of the request changes 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://ecs.amazonaws.com/onca/xml, and the service name, AWSECommerceService.

Amazon hosts many web services in addition to Product Advertising API, including Mechanical Turk and 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.

Locale Endpoint
CA

http://ecs.amazonaws.ca/onca/xml

https://aws.amazonaws.ca/onca/xml
DE

http://ecs.amazonaws.de/onca/xml

https://aws.amazonaws.de/onca/xml
FR

http://ecs.amazonaws.fr/onca/xml

https://aws.amazonaws.fr/onca/xml
JP

http://ecs.amazonaws.jp/onca/xml

https://aws.amazonaws.jp/onca/xml
UK

http://ecs.amazonaws.co.uk/onca/xml

https://aws.amazonaws.co.uk/onca/xml
US

http://ecs.amazonaws.com/onca/xml

https://aws.amazonaws.com/onca/xml

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

http://ecs.amazonaws.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 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 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 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 very 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 browsenode 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 only work with a subset of all Product Advertising API response groups. The valid response groups that each Product Advertising API operation can use is listed in the Product Advertising API 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 operation name and the input parameters sent in the request. The other response groups used by default vary by the 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 Guide 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.

previous page start next page