Tutorial: Using the MTurk API with the AWS SDK for Java

In previous blog posts, we’ve shown how to use the Amazon Mechanical Turk (MTurk) Application Programming Interface (API) using the AWS Software Development Kits (SDKs) for Node.js, Javascript with React, Python, and Ruby. We’ll continue to post tutorials to help Requesters get started quickly with MTurk’s API.

In today’s tutorial, we will step through how to setup and make your first API calls again the MTurk API for Java. We will be using the popular Eclipse Integrated Development Environment (IDE) and the AWS Toolkit for Eclipse. Let’s get started.

Setting things up

To begin, we’ll first download and install Eclipse here:

https://www.eclipse.org/downloads/

For this tutorial, we’ll be using Eclipse Oxygen 3.A (April 2018). Once installed, we’ll then install the AWS Toolkit for Eclipse by following these steps:

Now, let’s go to the Menu bar and select New then Project. A dialog box should appear that will look similar to this:

Select AWS Java Project, and click Next >. Now we will be asked to provide a name for our new project (we’ll name ours mturk-app for this tutorial). It should look like this:

If you want to use different credentials than those found in your ~/.aws/credentials file, select them under the AWS Credentials header, in the Select profile: dropdown. For this tutorial, we will use the default credentials as shown above.

Next click Finish to proceed. Once complete, your screen should look similar to this:

Creating our first program

Often, the best place to start when configuring a new language and a new API is to write a simple program to ensure that we’re correctly compiling, calling the API, and receiving the expected result. MTurk offers a simple, read-only API called GetAccountBalance that is useful to verify that our application is correctly calling the MTurk API. Our first program will be to call that API.

Let’s use sample code that’s already available in the MTurk Code Samples repository on GitHub here:

aws-samples/mturk-code-samples

We’ll be working with the sample app called GetAccountBalanceSample that can be found here. First, let’s create our GetAccountBalanceSample class by clicking the right mouse button on the src/main/java and selecting New > Class. It should look like this:

From there, we will delete all characters in the Package: field, enter the class name GetAccountBalanceSample and click Finish to proceed. It should look like this:

Our Eclipse IDE screen should now look like this:

Next, we will open the sample code from GitHub for GetAccountBalanceSample found here:

https://github.com/aws-samples/mturk-code-samples/blob/master/Java/GetAccountBalanceSample.java

and paste it into our editor, completely replacing any existing code in the GetAccountBalanceSample.java file. Once you’ve pasted it in, your Eclipse IDE screen should look like this:

Drumroll, please….

Now we’ll actually run our first program. To do this, click the right mouse button anywhere in the GetAccountBalanceSample.java code editor window. A menu will appear and you’ll select Run As then Java Application. It should look like this:

You should see output that looks similar to the following:

SANDBOX - Your account balance is 10000.00
PRODUCTION - Your account balance is 384.72

And your screen should look similar to this:

Congratulations! You’ve just executed your first Java program calling the MTurk API with the AWS SDK. Nice work.

Wrapping up

Today, we’ve just scratched the surface of what’s possible with the AWS SDK for Java and the MTurk Requester API. In future tutorials, we’ll build on this to show readers how to do even more. In the meantime, you can learn more about the MTurk API by accessing the MTurk API documentation here. You can also check out more Java sample code for the AWS SDK and MTurk API here.

We hope you enjoyed today’s tutorial. If you have any questions, please post a question to our MTurk forums. To become a Requester, sign up here. Want to contribute as a Worker customer? Get started here.