The Ruby, JavaScript, and Perl files I have posted below may be useful to someone who wants to access MTurk’s APIs to create HITs. Basic tasks (e.g., creating a HIT) and intermediate tasks (giving a “bonus” to a worker) can be accomplished easily by using Amazon’s web interface. Advanced tasks (e.g., sending e-mail notifications to a long list of workers who have completed your previous HITs) cannot be accomplished with the web interface. There is a striking contrast between the ease of doing tasks with the web interface and the difficulty of doing tasks with the API. That difference is akin to the difference between buying a car and building a car entirely from custom parts.
One source of the difficulty with using the MTurk API is that Amazon’s documentation (e.g., here) seems to suggest your REST requests should be authenticated with Signature Version 2. Requests to MTurk APIs with version 2 signatures will fail without explanation because, as of this writing, MTurk continues to use Signature Version 1. Another source of the difficulty is that the Ruby software development kit provided by Amazon is woefully inadequate. Yet another source of the difficulty is the hobbles that Amazon put on requesters, such as allowing “and” for combining worker requirements but not allowing “or” for the same purpose. I suppose all the hobbles are designed to prevent exploits, but the API landscape is littered with hobbles to the point of obstruction. For all those reasons I found developing these files to be frustrating, so I stopped editing the files the moment I got everything working successfully. Nowadays, the only thing I change in them is the bare necessities (e.g., the URL for the Qualtrics q’re that I want to launch).
In case someone else finds my solution helpful in their own adventures, I’ve posted in this location the files that I use. The three files all play different roles. The Ruby program makes a REST request to MTurk to create a new MTurk HIT with an “external question.” When a worker views the MTurk HIT, the HIT calls the HTML/JavaScript file as the “external question” (screenshot). When a worker accepts the HIT, the JavaScript program checks my server to see if their WorkerID or IP address are already in my records as a past participant. If so, the JavaScript program informs the worker they are ineligible (screenshot). If not, the JavaScript program asks some initial screening questions (screenshot) and calls the Perl CGI program. The Perl program writes their WorkerID and IP address to the records on my server, and if the participant meets the initial screening requirements, the Perl program provides a link to a Qualtrics q’re , it accepts the code from the final screen of the Qualtrics q’re, and then it submits the HIT to MTurk (screenshot).
Familiarity with Ruby, JavaScript, and Perl would be necessary for you to adapt these files for your situation, but I hope these files will be helpful if you want to navigate the unique weirdness of dealing with MTurk APIs.
– Eric DeRosia