This article explains how to make a REST request to the Mechanical Turk web service.
The 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 and Schema Locations.
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, such as:
<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"). The above example would appear in a REST request as follows:
http://mechanicalturk.amazonaws.com/onca/xml?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:
...&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. In an XML message, this structure looks like this:
<QualificationRequirement> <QualificationTypeId>789RVWYBAZW00EXAMPLE</QualificationTypeId> <Comparator>GreaterThan</Comparator> <Value>18</Value> </QualificationRequirement>
A single QualificationRequirement is specified in a REST request as follows:
http://mechanicalturk.amazonaws.com/onca/xml?Service=AWSMechanicalTurkRequester
[...]
&QualificationRequirement.1.QualificationTypeId=789RVWYBAZW00EXAMPLE
&QualificationRequirement.1.Comparator=GreaterThan
&QualificationRequirement.1.Value=18
Multiple QualificationRequirement values are specified as follows:
http://mechanicalturk.amazonaws.com/onca/xml?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 and Schema Locations.
The following example is a REST request (GET method) that calls the GetAccountBalance operation.
http://mechanicalturk.amazonaws.com/onca/xml?Service=AWSMechanicalTurkRequester &AWSAccessKeyId=[the Requester's Access Key ID] &Operation=GetAccountBalance &Signature=[signature for this request] &Timestamp=[your system's local time]