JATOS API

info

Using the JATOS API requires some advanced knowledge of HTTP and how to call APIs from e.g. a programming language or a terminal. If you just want to run a study with JATOS this is probably not what you need. Anything that you can do (programmatially) with the API can also be done (by hand) with JATOS' GUI.

Introduction

Since version 3.8.1 JATOS offers an (HTTP) API to make integrating JATOS into other tools easier. One common usage of the API is to call JATOS directly from Python, R, Matlab (or any other programming language) in an automated and programatic fashion.

Things that are possible with the API:

• Import/export studies
• Update your study by uploading/downloading/deleting single study assets files
• Export results
• Export study/componnent properties
• Get study codes (to build study links that can be distributed to participants)

Have a look and try it out

You can even try out the API with your local JATOS. Here's how:

1. Generate a token in your local JATOS. (The JATOS API uses personal access tokens with bearer authentication.)
2. Copy your token
3. Go to petstore.swagger.io. You'll see all API endpoints and their descriptions.
4. At the top of the Swagger page, you'll find a green 'Authorize' button. Paste the JATOS token into Authorize -> Bearer Auth. Don't forget to click on Authorize.
5. Choose the server http://localhost:9000 (probably already set)
6. Try it out! (Click on each link to try the corresponding endpoint with pre-loaded defaults)

OpenAPI specification

The JATOS API uses OpenAPI 3 for specification. You can use petstore.swagger.io to have an easy navigatable page.

The API is work in progress (this is the first version). To request any additional endpoints, please write a GitHub issue.

Authentication

The JATOS API uses bearer authentication. It's pretty simple.

From swagger.io:

Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name "Bearer authentication" can be understood as "give access to the bearer of this token." The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the Authorization header when making requests to protected resources.

Every HTTP request to the API needs this header (replace <token> with your token):

Authorization: Bearer <token>

And an example in different tools/languages with the endpoint /jatos/api/v1/admin/token that just returns some info about the used token:

curl

curl -i -H "Authorization: Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f" https://example.com/jatos/api/v1/admin/token

Python

import requests

headers = {
    'Authorization': 'Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f',
}
response = requests.post('https://example.com/jatos/api/v1/admin/token', headers=headers)

R

require(httr)

headers = c(
  `Authorization` = "Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f"
)
res <- httr::GET(url = "https://example.com/jatos/api/v1/admin/token", httr::add_headers(.headers=headers))

JavaScript

fetch('https://example.com/jatos/api/v1/admin/token', {
  headers: {
    'Authorization': 'Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f'
  }
});

MATLAB

%% HTTP Interface
import matlab.net.*
import matlab.net.http.*

header = HeaderField('Authorization', 'Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f');
uri = URI('https://example.com/jatos/api/v1/admin/token');
response = RequestMessage('get', header).send(uri.EncodedURI);

PowerShell

$headers=@{}
$headers.Add("Authorization", "Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f")
$response = Invoke-WebRequest -Uri 'https://www.example.com/jatos/api/v1/admin/token' -Method GET -Headers $headers

Personal access tokens

The JATOS API uses personal access tokens (PATs or API tokens).

From wikipedia:

a personal access token (or PAT) is a string of characters that can be used to authenticate a user when accessing a computer system instead of the usual password. Though associated with a single account, multiple PATs may be added, and can be manipulated independently of the password associated with that account, including creation and revocation of PATs without altering the password.

Unlike other systems (e.g. GitHub) JATOS' tokens have no roles or scopes. A token has the same access as the user they are associated with. Therefore, naturally, a token can only be used to access studies or their result data if the associated user is a member of this study. Only admin tokens (tokens associated with an admin user) can access the administration endpoints.

How to generate a token

Go to the user menu (click on your name in the top-right header). Then click the button My API tokens.

In the pop-up window click the button New Token". Then choose a descriptive _name (doesn't have to be unique). Choose the time period when the token is about to expire. Click Generate.

Now your token will be shown. Copy it to a safe place. It will never be shown to you again.

In the token overview windows you can temporarily deactivate a token or delete it altogether.

How to import a study

The endpoint to import a study, /jatos/api/v1/study, can be a bit tricky. It uses POST request with the header Content-Type: multipart/form-data to upload the a study archive file (JZIP) in binary format.

Here are some examples in different tools/languages. They all upload a JZIP file named test.jzip:

curl

curl -X 'POST'   'https://example.com/jatos/api/v1/study'   -H 'accept: application/json' -H 'Authorization: Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f'   -H 'Content-Type: multipart/form-data'   -F 'study=@test.jzip'

Python

import requests

headers = {
    'accept': 'application/json',
    'Authorization': 'Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f',
    # requests won't add a boundary if this header is set when you pass files=
    # 'Content-Type': 'multipart/form-data',
}

files = {
    'study': open('test.jzip', 'rb'),
}

response = requests.post('https://example.com/jatos/api/v1/study', headers=headers, files=files)

R

require(httr)

headers = c(
  `Authorization` = "Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f"
)
res <- httr::GET(url = "https://example.com/jatos/api/v1/admin/token", httr::add_headers(.headers=headers))

JavaScript

const form = new FormData();
form.append('study', File(['<data goes here>'], 'test.jzip'));

fetch('https://example.com/jatos/api/v1/study', {
  method: 'POST',
  headers: {
    'accept': 'application/json',
    'Authorization': 'Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f',
    'Content-Type': 'multipart/form-data'
  },
  body: form
});

MATLAB

%% HTTP Interface
import matlab.net.*
import matlab.net.http.*
import matlab.net.http.io.*

header = [
    field.AcceptField(MediaType('application/json'))
    HeaderField('Authorization', 'Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f')
    HeaderField('Content-Type', 'multipart/form-data')
]';
uri = URI('https://example.com/jatos/api/v1/study');
body = MultipartFormProvider('study', FileProvider('test.jzip'));
response = RequestMessage('post', header, body).send(uri.EncodedURI);

PowerShell

$headers=@{}
$headers.Add("accept", "application/json")
$headers.Add("Authorization", "Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f")
$headers.Add("Content-Type", "multipart/form-data")
$response = Invoke-WebRequest -Uri 'https://example.com/jatos/api/v1/study' -Method POST -Headers $headers

Deactivate the JATOS API

By default the API is activated and ready to use. If, for whatever reasons, you want to turn it off, edit the conf/jatos.conf (or conf/production.conf in version < 3.8.3) in the JATOS installation folder. Search for jatos.api.allowed and remove the #:

jatos.api.allowed = false