REST API¶

Turkle has a REST API for administration of users, groups, projects, and batches. A full OpenAPI schema of the API is available at /api/schema/.

The API uses integer identifiers for all the objects. These identifiers are included in the response when creating or listing objects. In the admin UI, the identifier is included in any URL for that object.

Client¶

Turkle has an API client that can be installed through pip:

pip install turkle-client

The client operates similar to git or docker in that it has sub-commands. With each call you include the sub-command such as users and then an action like list:

turkle-client users list

Full details on configuring the client is found on turkle-client GitHub page. Below are details on the API that are wrapped by the client.

Authentication¶

It requires token-based authentication and tokens can be created per user in the admin UI. Once a token has been created, it is passed as a header in the request:

token = 'ABCDEF'
headers = {'Authorization': f'Token {token}'}
resp = requests.get('http://localhost:8000/api/users/', headers=headers)

With curl this looks like this:

curl -H "Authorization: Token ABCDEF" http://localhost:8000/api/users/

Users¶

Listing users¶

Perform a get on /api/users/. The response is paginated and includes next and previous links to walk the user list.

Creating a user¶

Perform a post on /api/users/. The payload at a minimum must include username and password:

{
  "username": "jsmith",
  "first_name": "John",
  "last_name": "Smith",
  "email": "jsmith@example.org",
  "password": "p@ssw0rd"
}

Retrieving a user¶

Perform a get on /api/users/{id}/ where id is the user’s integer identifier.

To retrieve based on username. perform a get on /api/users/username/{username}/.

Update a user¶

Perform a patch on /api/users/{id}/ where id is the user’s integer identifier. The JSON payload is a dictionary of fields to update.

Groups¶

Listing groups¶

Perform a get on /api/groups/. The response is paginated and includes next and previous links to walk the list.

Creating a group¶

Perform a post on /api/groups/. The payload must include the name of the group and a list of user integer identifiers:

{
  "name": "Spanish",
  "users": [7, 34, 35, 36]
}

Retrieving a group¶

Perform a get on /api/groups/{id}/ where id is the group’s integer identifier.

To retrieve based on a group name. perform a get on /api/groups/name/{name}/. This will return a list of groups that exactly match that group name. It is a list since group names are not required to be unique in Turkle.

Adding users to a group¶

Perform a post on /api/groups/{id}/users/ where id is the group’s integer identifier.

The payload is a dictionary with a key of users which is a list of user integer identifiers.

Projects¶

Listing projects¶

Perform a get on /api/projects/. The response is paginated and includes next and previous links to walk the list.

Creating a project¶

Perform a post on /api/projects/. The payload must include the name of the project, the html template, and the template filename:

{
  "name": "Image Contains",
  "html_template": "<html>template as a string here</html>,
  "filename": "image_contains.html"
}

Optional fields include active, allotted_assignment_time, assignments_per_task, and login_required.

Retrieving a project¶

Perform a get on /api/projects/{id}/ where id is the project’s integer identifier.

Update a project¶

Perform a patch on /api/projects/{id}/ where id is the project’s integer identifier. The JSON payload is a dictionary of fields to update and can include the html_template.

Batches¶

Listing batches¶

Perform a get on /api/batches/. The response is paginated and includes next and previous links to walk the list.

Creating a batch¶

Perform a post on /api/batches/. The payload must include the name of the batch, the project identifier, and the csv data and filename:

{
  "name": "Bird Photos",
  "project": 20,
  "filename": "image_contains.csv",
  "csv_text": "csv as string"
}

Optional fields include active, allotted_assignment_time, assignments_per_task, and login_required.

Retrieving a batch¶

Perform a get on /api/batches/{id}/ where id is the batch’s integer identifier.

Update a batch¶

Perform a patch on /api/batches/{id}/ where id is the batch’s integer identifier. The JSON payload is a dictionary of fields to update and cannot include the csv data. If a bad batch was created, delete it using the admin UI.

Additional tasks can be added to an existing batch by a post to /api/batches/{id}/tasks/. The payload is a dictionary with a key of csv_text. The fields in the CSV data must match the fields in html template of the project.

Batch status¶

To download the input data for a batch as a CSV file, do a get on /api/batches/{id}/input/.

To download the results data for a batch as a CSV file, do a get on /api/batches/{id}/results/.

To get up-to-date progress for a batch, do a get on /api/batches/{id}/progress/.

Permissions¶

Projects and Batches can be restricted to particular users or groups. To retrieve the current permissions, perform a get on /api/projects/{id}/permissions/ (replacing “projects” with “batches” to get a batch’s permissions).

To add additional users and groups to a project’s permissions, perform a post on /api/projects/{id}/permissions/ with a payload of users and groups:

{
  "users": [],
  "groups": [29, 63]
}

To replace the current permissions for a project, perform a put on the endpoint.