Taskfarm REST API

Resource	Operation	Description
	GET /
run	POST /api/run	create a new run
runs	GET /api/runs	get a list of all runs
	POST /api/runs/(string:uuid)/restart	restart all tasks of a run
	GET /api/runs/(string:uuid)/tasks/(int:taskID)	information about a particular task
	PUT /api/runs/(string:uuid)/tasks/(int:taskID)	update a particular task
	POST /api/runs/(string:uuid)/task	request a task for run
	GET /api/runs/(string:uuid)	get information about a particular run
	DELETE /api/runs/(string:uuid)	delete a particular run
token	GET /api/token	get the authentication token
worker	POST /api/worker	create a worker

GET /

print info about taskfarm server

POST /api/run

create a new run

Request JSON Object

• numTasks (int) – the number of tasks of the run

Response JSON Object

• id (int) – run ID

• uuid (string) – run UUID

• numTasks (int) – the number of tasks

Status Codes

• 400 Bad Request – when numTask is missing

GET /api/runs

get a list of all runs

Response JSON Array of Objects

• id (int) – run ID

• uuid (string) – run UUID

• numTasks (int) – the number of tasks

DELETE /api/runs/(string: uuid)

delete a particular run

Parameters

• uuid (string) – uuid of the run

Status Codes

• 404 Not Found – when the run does not exist

• 204 No Content – when the run was successfully deleted

GET /api/runs/(string: uuid)

get information about a particular run

Parameters

• uuid (string) – uuid of the run

Query Parameters

• info – request particular information about the run.

Status Codes

• 404 Not Found – when the run does not exist

• 404 Not Found – when unkown information is requested

• 200 OK – the call successfully returned a json string

The info query parameter can be one of percentDone, numWaiting, numDone, numComputing to get particular information of the run. By default info is the empty string and call returns a json object containing all those pieces of information.

POST /api/runs/(string: uuid)/restart

restart all tasks of run

Parameters

• uuid (string) – uuid of the run

Query Parameters

• all (string) – can be True/False (default). When set to to True restart all tasks otherwise restart only partially completed tasks

Status Codes

• 400 Bad Request – when run with uuid does not exist

• 404 Not Found – when parameter all has wrong value

• 204 No Content – success

POST /api/runs/(string: uuid)/task

request a task for run

Parameters

• uuid (string) – uuid of the run

Request JSON Object

• worker_uuid (string) – uuid of worker requesting a task

Response JSON Object

• id (int) – task ID

• task (int) – task number

• percentCompleted (float) – percentage compelted of task

• status (string) – task status, can be one of waiting, computing, done

Status Codes

• 400 Bad Request – when worker_uuid is not present

• 404 Not Found – when worker does not exist

• 404 Not Found – when run does not exist

• 204 No Content – no more tasks

• 201 Created – new tasks

GET /api/runs/(string: uuid)/tasks/(int: taskID)

get information about a particular task

Parameters

• uuid (string) – uuid of the run

• taskID (int) – the task’s ID

Query Parameters

• info – request particular information about the task

Status Codes

• 404 Not Found – when the run does not exist

• 404 Not Found – when the taskID < 0 or when taskID is larger than the number of tasks

• 404 Not Found – when unkown information is requeste

• 200 OK – the call successfully returned a json string

The info query parameter can be one of status or percentDone to get particular information of the task. By default info is the empty string and call returns a json object containing all those pieces of information.

PUT /api/runs/(string: uuid)/tasks/(int: taskID)

update a particular task

Parameters

• uuid (string) – uuid of the run

• taskID (int) – the task’s ID

Request JSON Object

• percentCompleted (float) – percentage of task completed

• status (string) – status of task, can be waiting, computing, done

Status Codes

• 400 Bad Request – an error occurred updating the task

• 204 No Content – the task was successfully updated

GET /api/token

get the authentication token

Response JSON Object

• token (string) – the authentication token

POST /api/worker

create a worker

Request JSON Object

• uuid (string) – worker uuid

• hostname (string) – hostname where worker is running

• pid (int) – process ID (PID) of worker

Response JSON Object

• uuid (string) – worker uuid

• id (int) – worker ID

Status Codes

• 400 Bad Request – when input json is incomplete

• 201 Created – when worker was created successfully