Tango REST API

REST API version 1.1

• Dave O' Hallaron 10/2013
• Mihir Pandya 02/2014

Contents

• Introduction
• Authentication
• Autograding Requests
  • open, upload, addJob, poll
• Administrative Requests
• Implementation Notes
• Future Work

Introduction

Our aim is to provide a stand-alone autograding service that can serve clients from around the world. Towards this end, we propose replacing the current Thrift-based Tango server with one based on a simple, universal, HTTP-based REST interface. This document describes the proposed REST interface.

Authentication

In order to have access to the REST interface of the Tango server, clients will first have to obtain a key from the Tango server. This key is a unique identifier of the client and it must be supplied with every HTTP request to the Tango server. If the Tango server fails to recognize the key, it does not entertain the request and returns an error message as part of the response body. The key is randomly generated (/dev/random), at the time of request.

Autograding Requests

Here is a description of the requests that clients use to submit autograding jobs.

open

A request to open consists of the client's key and an identifier for every lab, which is likely to be a combination of the course name and the lab name (i.e. courselab). open checks if a directory for courselab exists. If the directory does not exist, it is created and a folder for output files is also created within the courselab directory. Since no files exist in the newly created directory, an empty list of MD5 hashes is returned. If a directory for courselab exists, a list of MD5 hashes corresponding to every file in that directory is returned.

Request header: GET autograde.me/open/key/courselab
Request body: empty
Response body: { "statusMsg": <string>, "statusId": <int> "files": [<string>, <string>, <string>, ...] }

upload

After receiving a list of MD5 hashes of files that exist on the Tango server, the client can choose to upload files that are different from the ones on the Tango server that are used in autograding via successive upload commands. For each upload, filename gives the name of the file. One of these files must be Makefile, which needs to contain a rule called autograde (command to drive the autograding process).

Request header: POST autograde.me/upload/key/courselab
Request body: <file>
Response body: { "statusMsg": <string>, "statusId": <int> }

addJob

After uploading the appropriate files, the client uses this command to request autograding service for the files specified as files in courselab and on an instance of a particular VM image. One of the specified files needs to be the Makefile, which must contain a rule called autograde. Clients can also specify an optional timeout value (timeout) and maximum output file size (max_kb). This command is non-blocking and returns immediately with a status message. Additionally, the command accepts an optional parameter, callback_url. If the callback_url is specified, then the Tango server sends a POST request to the callback_url with the output file once the job is terminated. If the callback_url is not specified, the client can then send a poll request for the output_file to check the status of that job and retrieve the output file from the Tango server if autograding is complete.

Request header: POST autograde.me/addJob/key/courselab
Request body:

{
  "image": <string>,           # required VM image (required)
  "files": [<string>, ...],    # required list of filenames to be used for autograding
  "jobName": <string>,         # required name of job
  "output_file": <string>,     # required name of output file
  "timeout": <int>,            # optional timeout value (secs)
  "max_kb": <int>,             # optional max output file size (KB)
  "callback_url": <string>     # optional URL for POST callback from server to client
}

Response body: { "statusMsg": <string>, "statusId": <int>, "jobId": <int> }

poll

Check if the autograding for outputFile has completed. If not, return 404: Not Found and a status message, otherwise return the file in the response body, and free all resources held by the job.

Request header: GET autograde.me/poll/key/courselab/outputFile
Request body: empty
Response body:
<autograder output file> if autograding successful {"statusMsg": <string>, "statusId": <int> } otherwise

Administrative Requests

Here are the requests that administrators use to manage the autograding service, typically from a command line client.

info

This is the "hello, world" request for the service. It returns a JSON object with some basic stats about the service, such as uptime, number of jobs, etc.

Request header: GET autograde.me/info
Request body: empty
Response body: JSON info object

jobs

Return a list of jobs. If deadjobs is defined, then return a list of recently completed jobs. Otherwise, return the list of currently running jobs. Note: This isn't strictly an admin request, since clients might find it useful to display jobs status, as we do in the Autolab front end.

Request header: POST autograde.me/jobid
Request body: { "deadjobs": <1 or 0> } # optional
Response body: JSON jobs object

pool

Returns a JSON object that provides info about the current state of a pool of instances spawned from some image. The response gives the total number of instances in the pool, and the number of free instances not currently allocated to any job.

Request header: GET autograde.me/pool/image
Response body: JSON pool object

prealloc

Creates a pool of num identical instances spawned from image.

Request header: POST autograde.me/prealloc/image/num
Request body: empty
Response body: { "status": <string> }

Implementation Notes

• Tango will maintain a directory for each of the labs in a course, which is created by open. All output files are stored within an output folder in this directory. Besides the runtime job queue, no other state is necessary.

  At autograding time, Tango will copy files specified by the files parameter in addJob to the VM. When the VM finishes, it will copy the output file back to the lab directory.

Future Work

• Construct a garbage collection mechanism that periodically removes stale output files from the lab directory.
• deleteJob, which, given the jobId, terminates a job that is currently running or waiting to be executed.