Making REST Requests

The Amazon Mechanical Turk web service supports REST requests for calling service operations. REST requests are simple HTTP requests, using either the GET method with parameters in the URL, or the POST method with parameters in the POST body. The response is an XML document that conforms to a schema. You might use REST requests when a SOAP toolkit is not available for your platform, or if REST requests would be easier to make than a heavier SOAP equivalent.

The location of the schema that describes the responses for the various operations is discussed in the section, WSDL Location.

	Note
	Amazon Mechanical Turk limits the velocity of requests. If you exceed the limit you will receive a 503 Service Unavailable error. It is highly unlikely that you will reach this limit with normal activity.

The API reference in this guide lists the parameters for each operation. Most parameters can be specified in a REST request using just the name of the parameter and an appropriate value, with the value URL-encoded as necessary to make the request a valid URL.

Some parameters have multiple components. For example, a HIT reward is specified as a Reward parameter, which includes an Amount and a CurrencyCode. In a SOAP request or in a response, this value would appear as an XML data structure. The following code sample demonstrates this data structure.

<Reward>
  <Amount>32</Amount>
  <CurrencyCode>USD</CurrencyCode>
</Reward>

In a REST request, the components are specified as separate parameters. The name of each component parameter is the main parameter name (such as "Reward"), a dot, a sequence number, a dot, and the component name (such as "Amount"). For example, the preceding example would appear in a REST request as follows:

http://mechanicalturk.amazonaws.com/?Service=AWSMechanicalTurkRequester
[...]
&Reward.1.Amount=32
&Reward.1.CurrencyCode=USD

For parameters that can be specified more than once in a single request, each parameter name includes a number to make it clear which values belong to each parameter. Parameters with single values simply use the name, a dot, and a number. This is shown in the following example.

...&ParameterName.1=valueOne&ParameterName.2=valueTwo...

Parameters with component values use the name of the main parameter, followed by a dot, the number, a dot, and the component name. For example, a request for the CreateHIT operation can specify more than one QualificationRequirement for the HIT being created. The value of the QualificationRequirement parameter is a structure with three components, QualificationTypeId, Comparator, and Value. For example, in an XML message, this structure looks like this:

<QualificationRequirement>
  <QualificationTypeId>789RVWYBAZW00EXAMPLE</QualificationTypeId>
  <Comparator>GreaterThan</Comparator>
  <Value>18</Value>
</QualificationRequirement>

The following example shows how a single QualificationRequirement is specified in a REST request.

http://mechanicalturk.amazonaws.com/?Service=AWSMechanicalTurkRequester
[...]
&QualificationRequirement.1.QualificationTypeId=789RVWYBAZW00EXAMPLE
&QualificationRequirement.1.Comparator=GreaterThan
&QualificationRequirement.1.Value=18

The following example shows how multiple QualificationRequirement values are specified.

http://mechanicalturk.amazonaws.com/?Service=AWSMechanicalTurkRequester
[...]
&QualificationRequirement.1.QualificationTypeId=789RVWYBAZW00EXAMPLE
&QualificationRequirement.1.Comparator=GreaterThan
&QualificationRequirement.1.Value=18
&QualificationRequirement.2.QualificationTypeId=231FOOYBARW00EXAMPLE
&QualificationRequirement.2.Comparator=GreaterThan
&QualificationRequirement.2.Value=75

In addition to the parameters found in request data structures, REST requests have additional parameters to indicate the name of the service and the version of the API. (SOAP requests have this information embedded in the SOAP URL.) For more information about these parameters and their values, see Common Parameters . For more information about service versions, see WSDL Location.

The following example is a REST request (GET method) that calls the GetAccountBalance operation.

http://mechanicalturk.amazonaws.com/?Service=AWSMechanicalTurkRequester
&AWSAccessKeyId=[the Requester's Access Key ID]
&Version=2008-08-02
&Operation=GetAccountBalance
&Signature=[signature for this request]
&Timestamp=[your system's local time]
&ResponseGroup.0=Minimal
&ResponseGroup.1=Request