Blog

Tutorial: Amazon.com Search API

Posted on
REST Syntax

One of the advantages to using REST is that its syntax is simple, which makes REST requests easy to read. This section summarizes all of the REST syntax rules that you must keep in mind when creating a REST request.

Spaces in Requests

Because a REST request is a URL, there can be no spaces between the parts of a request. A browser will stop reading when it runs across the first space. For example, if the last parameter read, Keywords=Blue Shirts, the request would end on “Blue.” “Shirts” would never be read. If you have key words, such as names, that do have spaces in them, you must URL-encode the space using %20. For the preceding example to work, you would include a URL-encoded space, as follows.

Keywords=Blue%20Shirts

The same problem occurs if you put spaces between the parameters in a request, as shown in the following example.

SearchIndex=Apparel& Keywords=Shirt

In this example, the request would end with “Apparel&.” Often, this kind of mistake returns an error because parameters required by the operation are not read. So, make sure to remove all spaces within a request.

Separator Characters

The question mark (?) and ampersand (&) separate the terms in a REST request. The first term in the request must always be the endpoint, which, in the preceding example, is, http://ecs.amazonaws.com/onca/xml. A question mark always follows the endpoint. The question mark tells the Amazon Associates Web Service web servers to start parsing the request for parameters. Ampersands separate all of the other parameter name-value pairs in the request. The order of the parameter name-value pairs is inconsequential, as long as they all occur after the question mark.

Setting Parameter Values

Request parameter values are set using the format.

ParameterName=value

The following example is a parameter/value pair.

Operation=ItemSearch

Parameter values must be URL-encoded. There are some characters, such as an asterisk or space, that cannot go into a URL. There are equivalents of these characters that you use in requests instead. For example, the URL encoded equivalent of a space is %20. So, instead of writing Name=John Smith you would write Name=John%20Smith.

Response Groups

A special parameter that is optional for all Amazon Associates Web Service 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.