Release Assembly - Turkification API

Project Overview

Our client want to use Amazon mturk to invite game players to play set of games. Each Human Intelligence Task (HIT) will be for completing a "task" (analogous to a subset of levels in the game versions) in exchange for payment. Ideally, we would keep this as short and simple as possible - i.e. one "task" gets the payment (instead of multiple progressive levels).

Game players will need to navigate to client website in order to play the games, client will user mturk API to login players, and to perform some other mturk operations. Also client wants to allow multiple teams to user same mturk account but with limited access. We will be launching multiple challenges to build the infrastructure to automate and simplify this process.

Competition Task Overview

In this challenge we will build a REST API for common functionality that game developer teams will need access to in order to automate HIT manipulation.

Technology Stack

• ExpressJS framework
• PostgreSQL DB
• Any compatible ORM node module (i.e. node-orm2, sequelizejs, .. others)
• OAuth 2.0

OAuth Server

API needs to be protected behind an OAuth server, here is how we will do it :

• We will have a user model that define users who have access to the API (same users will have access admin portal that we will build in future ), the user schema will be similar to this :
  • user email
  • password
  • domain id
    • We need to control who can manipulate HITs under of each game development team, so we need to support multi-tenancy where HITs are associated with domains.
  • role - each user may have roles associated to his/her account, roles will be related to domains, i.e. user can have admin access domain A but user access to domain B, roles are :
    • global admin : user with this role can have read/write access to any domain.
    • admin : user with this role can have read/write access to the associated domain.
    • user : user with this role can have read access to the associated domain.
• We will use OAuth 2.0 Server
• OAuth server will support creating oauth tokens via two grant types :
  • Authorization Code Grant
  • Resource Owner Password Credentials Grant

API Requirements

We will implement the following API endpoints in this challenge :

• Create/Disable/Extend HIT :
  • They will work as wrapper to mturk API :
    • Create HIT
    • Disable HIT
    • Extend HIT
  • These operations require at least 'admin' role.
  • We will have a Task model to store information about HIT, the model will updated in all three operations, the schema :
    • mturk_hit_id - the mturk HIT id and will work as the primary id of the model
    • mturk title
    • task id - this will store the task id team will use to associate created HIT with the task to be used when rendering the game for mturk workers.
    • domain id
    • created by
    • created date
    • modified by
    • modified date
  • Endpoints routes :
    • POST /hits
      • this will be used for creating hits
      • Each item input to this method will be identical to input of mturk create hit api operation including the task id.
      • The flow :
        • There must be valid user with 'admin' role to access this operation.
        • Create mturk HIT
        • If previous step is successful then insert new Task record and return it to caller with response code 200
        • If failed, propagate the error from mturk to caller
        • If any other errors happen, then propagate to caller
    • PUT /hits
      • this will be used to extending hits
      • Input to this method will be identical to input of mturk extend hit api operation.
      • The flow :
        • There must be valid user with 'admin' role to access this operation.
        • call mturk to extend HIT
        • If previous step is successful then update HIT record and return 204 http status code to caller.
        • If failed, propagate the error from mturk to caller
        • If any other errors happen, then propagate to caller
    • DELETE /hits
      • this will be used to disable hits
      • call mturk disable HIT to disable HIT
      • If previous step is successful then update HIT record and return 204 http status code to caller.
      • If failed, propagate the error from mturk to caller
      • If any other errors happen, then propagate to caller
• Get ALL Hits
  • Endpiont route : GET /hits
  • This operation requires at least user with 'user' role to access it.
  • Retrieve all Tasks associated with the logged in user domain id.
  • Return results to caller.
• Get HIT
  • endpoint route : GET /hit/:mturk_hit_id
  • The operation requires at least user with 'user' role to access it.
  • the target hit should be under same domain as the authorized user domain id.
  • The flow will be :
    • retireve Task from db.
    • retrieve corresponding HIT from mturk using Get Hit operation.
    • populate task with all additional returned properties from previous step.
    • return the task to caller.

Postman REST Client

• http://www.getpostman.com/
• Create a Postman json file with request for all operations in scope in addition to the OAuth server requests.
• Include sample requests
• Don't include sample environment data

Folder Structure

• We are going to have a private git repository
• The folder structure will follow this structure:
  • moduledir/
    • controllers/
    • services/
    • models/
    • views/
    • confg/
      • All sensitive information, db connection info, specific environment variables must be set in configuration.
      • Configuration file should have default values.
      • Use .env environment variable to override default values.
    • package.json
    • app.js
    • jakefile.js
    • jake.sh
    • jake.bat
    • postman.json
    • readme.md
    • .gitignore (include common files and folders to be excluded in nodejs application)
• If you need to add any file or directory to the above folder structure you need to get explicit confirmation from Copilot in forums.
• Dependency modules will be added to package.json as dependencies will be installed by executing npm install along with the public nodejs modules

 

Final Submission Guidelines

Submission Deliverables

Below is an overview of the deliverables:

• a git folder with same structure as outlined above.
• A readme.md file detailing all information needed to setup and test the API. Use github flavored markup text. It should be part of the git folder submitted
• postman.json - it should be part of the git folder submitted
• text file with any notes to reviewer.
• You don't need to submit a word document for deployment guide.
• Submitting a video for how to setup and test api is a plus.

Final Submission

For each member, the final submission should be uploaded via the challenge detail page on topcoder.com.