This article describes the structure of responses from the Mechanical Turk web service.
In response to an operation call, the Mechanical Turk web service returns an XML data structure that contains the results of the call. This data conforms to a schema.
For SOAP requests, this data structure is the SOAP message body of the response. SOAP toolkits typically convert the response data into structures for use with your programming language, or allow you to specify your own data bindings.
For REST requests, this data structure is simply the body of the HTTP response. You can use a data binding method for REST responses, or use an XML parser directly to process the information.
Other than the use of a message envelope in the case of SOAP, the schema for the results is the same for both SOAP and REST responses. The SOAP WSDL imports an XSD file to define the response messages, and REST users can access the XSD file directly. For more information, see WSDL and Schema Locations.
The response message is returned in an XML element named after the operation. For example, the GetHIT operation returns a response element named GetHITResponse.
This element contains an OperationRequest element, and a "result" element.
The OperationRequest element contains information about the request. It always contains a RequestId element, a unique identifier assigned by the service to this specific operation call.
If an operation call is unsuccessful, OperationRequest contains an Errors element, with one or more Error elements. Each Error includes:
a Code that identifies the type of error the occurred,
a Message that describes the error condition in a human-readable form, and
zero or more Data elements that provide information about the error in a machine-readable form. Each Data has a Key and a Value.
If the Request response group is specified in the request, OperationRequest includes an Arguments element that lists all of the parameters that were sent to the operation. It contains one or more Arugment elements, each with a Name and a Value. For more information about response groups, see Common Parameters.
The response message always includes a result element, which contains the result data for the operation call. The name and contents of this element depend on the operation being called. Results are described for each operation in the API reference.
The result element also contains an IsValid element, with a Boolean value indicating if the request was valid. If this value is false, the result element usually does not contain anything else.
If the Request response group is specified in the request, the result element includes the contents of the request that correspond with the results in the result element. The name of this element depends on the operation. For example, a call to the GetHIT operation that includes the Request response group will include a GetHITRequest element along with the results. For more information about response groups, see Common Parameters.
The following is an example of a response message that could be returned by a call to the GetHIT operation. For a SOAP request, the message is returned as the response message body, inside a SOAP envelope. For a REST request, the message is returned directly as the body of the HTTP response.
<GetHITResponse>
<OperationRequest>
<RequestId>XA5TETQ3G6QF7EXAMPLE</RequestId>
</OperationRequest>
<HIT>
<Request>
<IsValid>true</IsValid>
</Request>
<HITId>123RVWYBAZW00EXAMPLE</HITId>
<CreationTime>2005-10-10T23:59:59.99Z</CreationTime>
[... other fields of the HIT ...]
</HIT>
</GetHITResponse>