The Mechanical Turk Service can be accessed using the SOAP web services messaging protocol, or using the REST method of HTTP requests with parameters. The SOAP interface is described by a Web Services Description Language (WSDL) document. REST requests return messages that conform to an XML Schema document.
The latest version of the WSDL for the Mechanical Turk Service can be found at the following URL:
http://mechanicalturk.amazonaws.com/AWSMechanicalTurk/AWSMechanicalTurkRequester.wsdl
The latest version of the XML Schema for the Mechanical Turk Service messages can be found at the following URL:
http://mechanicalturk.amazonaws.com/AWSMechanicalTurk/AWSMechanicalTurkRequester.xsd
The Mechanical Turk Service has several parameters and return values that contain XML data. The XML content must validate against the appropriate XML schema. For more information, see the QuestionForm data structure, the QuestionFormAnswers data structure, and the AnswerKey data structure.
The latest QuestionForm schema can be found at the following URL:
http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/QuestionForm.xsd
The latest QuestionFormAnswers schema can be found at the following URL:
http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/QuestionFormAnswers.xsd
The latest AnswerKey schema can be found at the following URL:
http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/AnswerKey.xsd
Note:
To conform to a schema, XML content must use namespace declarations that match the target namespace for the schema. The target namespace is declared at the top of the schema, as the "targetNamespace" attribute of the "xs:schema" element.
The schemas for QuestionForm, QuestionFormAnswers, and AnswerKey use namespace URIs similar to the URL at which the schema file can be found including the service version. See "Service Versions," below. For example:
<QuestionForm
xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/QuestionForm.xsd"
>
[...]
</QuestionForm>
If the service returns an error message about data not validating against the schema, make sure your namespace declaration matches the target namespace specified in the schema.
When a new version of the service API is released, previous versions are supported for a limited time to allow applications to continue to function until they are upgraded. The version of a service API is specified as a date, such as 2005-10-01.
The date of a version of the API can be found at the top of the WSDL file, in the targetNamespace attribute of the definitions element.
For information about which versions of the API are supported, visit the Amazon Web Services web site at http://aws.amazon.com/mturk.
To retrieve the WSDL or XML Schema for a specific version of the service API, include the version date in the URL. For example, to retrieve the WSDL for API version 2005-10-01:
http://mechanicalturk.amazonaws.com/AWSMechanicalTurk/2005-10-01/AWSMechanicalTurkRequester.wsdl
To retrieve the XML Schema for API version 2005-10-01:
http://mechanicalturk.amazonaws.com/AWSMechanicalTurk/2005-10-01/AWSMechanicalTurkRequester.xsd
Similarly for the QuestionForm, QuestionFormAnswers, and AnswerKey schemas for a specific API version:
http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/QuestionForm.xsd
http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/QuestionFormAnswers.xsd
http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/AnswerKey.xsd
For your application to use a specific version of the service API, the service needs to be told which version is being used with each request.
For SOAP requests, you do not need to include anything in your requests to indicate which service version you wish to access. SOAP requests always include the namespace from the WSDL, which includes the API version. The Mechanical Turk Service always knows which version to use for SOAP requests.
For REST requests, if your application requires a specific service or schema version, you must explicitly request the version to use by including the Version parameter in your request. The Version parameter ensures that the service does not return response elements that your application is not designed to handle.
The Version parameter is optional. If you do not include it, your response is based on the most recent schema.
Here is an example REST request that includes the Version parameter:
http://mechanicalturk.amazonaws.com/onca/xml?Service=AWSMechanicalTurkRequester
&AWSAccessKeyId=[the Requester's Access Key ID]
&Operation=GetHIT
&HITId=123RVWYBAZW00EXAMPLE
&Version=2005-10-01