Making SOAP Requests
This article explains how to make a SOAP request to the Amazon Mechanical Turk web service.
The Amazon Mechanical Turk web service supports the SOAP message protocol for calling service operations over an HTTP connection. The easiest way to use the SOAP interface with your application is to use a SOAP toolkit appropriate for your platform. SOAP toolkits are available for most popular programming languages and platforms.
The service's Web Services Definition Language (WSDL) file describes the operations and the format and data types of their requests and responses. Your SOAP toolkit interprets the WSDL file to provide your application access to the operations. For most toolkits, your application calls a service operation using routines and classes provided or generated by the toolkit.
The location of the WSDL file is discussed in the section, WSDL Location.
Amazon Mechanical Turk limits the velocity of requests. If you exceed the limit you will receive a 500 or 503 Service Unavailable error. It is highly unlikely that you will reach this limit with normal activity.
Using Operation Parameters With SOAP
The API reference in this guide describes the parameters for each operation and their values. You may find it useful to refer to the WSDL file directly to see how the parameters will appear in the XML of the request generated by your toolkit, and understand how your toolkit will make the operations available to your application code.
The Structure of a Request Message
A SOAP request is an XML data structure generated by your SOAP toolkit and sent to the service. As described by the service WSDL, the root element of this structure is named after the operation, and contains the parameter data for the request.
The root element contains the
Signature used to authenticate the
request as being sent by you. For more information on these
values, see AWS Request Authentication.
In addition to the request authentication parameters, the root
element contains a
Request element, which
contains the parameters of the specific operation being called.
For a description of an operation's parameters, see the
appropriate page for the operation in the Amazon Mechanical Turk API Reference.
Request element may also contain a
ResponseGroup parameter, which controls
how much data is returned by the service for an operation.
For more information about these parameters and their values, see Common Parameters.
The XML Message for a GetHIT SOAP Request
The following example is the XML for a SOAP message that calls
GetHIT operation. While you will
probably not be building the SOAP message for a service
request manually, it is useful to see what your SOAP toolkit
will try to produce when provided with the appropriate values.
Many SOAP toolkits require that you build a request data
structure similar to the XML to make a request.
contains the parameters common to all requests, and a
Request element that contains the
along with the
The following example calls the
<?xml version="1.0" encoding="UTF-8" ?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <GetHIT xmlns="https://mechanicalturk.amazonaws.com/AWSMechanicalTurkRequester/2014-08-15"> <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId> <Timestamp>2005-10-10T00:00:00.000Z</Timestamp> <Signature>
[...]</Signature> <Request> <HITId>123RVWYBAZW00EXAMPLE</HITId> <ResponseGroup>Minimal</ResponseGroup> <ResponseGroup>HITDetail</ResponseGroup> </Request> </GetHIT> </soapenv:Body> </soapenv:Envelope>