API docs by Redocly

(19.0.0)

Download OpenAPI specification:

This a spec for the (REST-) API of the IQB-Testcenter Application. It will be used to make backend's e2e-test and a mock-server for frontend's e2e-tests. It's the basis for our vision of continuous integration.

run test

get file by path

Retrieves a file from the workspace.

path Parameters
group_token
required
string
Example: static:group:sample_group

the (group-)auth-token for the workspace

path
required
string
Example: ws_1/Resource/SAMPLE_UNITCONTENTS.HTM

filename and path

Responses

Response samples

Content type
text/html;charset=utf-8
(the file's content)

get a test

Retrieves a certain test: It's content, state and the mode of current login-session. laststate is an array of key-value-pairs stored for this test. The test-mode is basically a string to be interpretated by the frontend. For more details about that see: https://pages.cms.hu-berlin.de/iqb/testcenter/pages/test-mode.html

  • run-hot-return and run-hot-restart - the real testing situation
  • run-review - for reviewers of of units and booklets
  • run-trial - for trying out the booklet
  • run-demo - for showcase only

From the backend's point of view these modes are all the same. Some have special meanings for the backend nevertheless:

  • monitor-group is the monitor account to supervise a group of testees
  • monitor-study is an account to supervise alls groups of a study
  • For run-hot-restart and demo every session is unique so the test will be restarted everytime a new session is started (eg after logout) and it will not possible to return to the previous session. Provided data from previous sessions will be stored anyway.
  • run-hot-return, run-hot-restart and run-trial - only these types of test wil be broadcasted via Broadcaster, so they can be views in the group-monitor.
  • run-review and run-trial - only these can create, change and delete reviews.
path Parameters
test_id
required
integer
Example: 1

id of a executed test

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Responses

Response samples

Content type
application/json
{
  • "mode": "run-hot-return",
  • "laststate": {
    },
  • "xml": "(contents of a booklet.xml)"
}

get a unit of a test

Retrieves a certain unit for a certain executed test - the booklet-file XML, last state and lock status.

You can insert an optional parameter /alias/{alias} in the end to obtain data if unit is defined with an alias in the booklet. This is an HotFix for https://github.com/iqb-berlin/testcenter-frontend/issues/261.

path Parameters
test_id
required
integer
Example: 1

id of a executed test

unit_name
required
string
Examples:
  • UNIT.SAMPLE -
  • UNIT.SAMPLE-2 -

unit-name (not alias!) as defined in booklet

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Responses

Response samples

Content type
application/json
Example
{
  • "state": {
    },
  • "dataParts": {
    },
  • "unitResponseType": "example-data-format",
  • "definition": ""
}

add review to unit

adds a review item to unit in a test

path Parameters
test_id
required
string
Example: 1

test-id - id of a test execution.

unit_name
required
string
Example: UNIT.SAMPLE

unit-name (or alias) as defined in booklet

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Request Body schema: application/json
priority
integer

priority, 1=critical, 2=medium, 3=optional

entry
required
string

text of the review entry

reviewer
string or null

name of the reviewer

categories
string

whitespace separated list of categories

originalUnitId
string

original unit id, in case the unit id in the URL was overwritten by an alias

Responses

Request samples

Content type
application/json
{
  • "entry": "I am a critical review item for unit 1",
  • "reviewer": "John Doe",
  • "priority": 1,
  • "categories": "content whatever",
  • "originalUnitId": ""
}

add review to booklet

adds a review item to a certain booklet

path Parameters
test_id
required
string
Example: 1

test-id - id of a test execution.

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Request Body schema: application/json
priority
integer

priority, 1=critical, 2=medium, 3=optional

entry
required
string

text of the review entry

reviewer
string or null

name of the reviewer

categories
string

whitespace separated list of categories

Responses

Request samples

Content type
application/json
{
  • "entry": "I am a critical review item for booklet 1",
  • "reviewer": "John Doe",
  • "priority": 1,
  • "categories": "content whatever"
}

get unit-level reviews of a unit

Retrieves all review items for a specific unit in a test. Only returns reviews created by the authenticated user.

path Parameters
test_id
required
integer
Example: 1

test-id - id of a test execution

unit_name
required
string
Example: UNIT.SAMPLE

unit-name (or alias) as defined in booklet

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

get booklet-level reviews for a test

Retrieves all review items for a specific booklet/test. Only returns reviews created by the authenticated user.

path Parameters
test_id
required
integer
Example: 1

test-id - id of a test execution

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

update a unit review

Updates an existing review item for a unit. Users can only update their own reviews.

path Parameters
test_id
required
integer
Example: 1

test_id - id of a test execution

unit_name
required
string
Example: UNIT.SAMPLE

unit-name (or alias) as defined in booklet

review_id
required
integer
Example: 1

unique ID of the review to update

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Request Body schema: application/json
priority
integer

priority, 0=lowest, 3=highest

entry
required
string

text of the review entry

reviewer
string or null

name of the reviewer

categories
string

whitespace separated list of categories

userAgent
string

user agent string

Responses

Request samples

Content type
application/json
{
  • "entry": "Updated review comment",
  • "reviewer": "John Doe",
  • "priority": 3,
  • "categories": "content design",
  • "userAgent": "Mozilla/5.0..."
}

delete a unit review

Deletes an existing review item for a unit. Users can only delete their own reviews.

path Parameters
test_id
required
integer
Example: 1

test-id - id of a test execution

unit_name
required
string
Example: UNIT.SAMPLE

unit-name (or alias) as defined in booklet

review_id
required
integer
Example: 1

unique ID of the review to delete

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Responses

update a booklet review

Updates an existing review item for a booklet/test. Users can only update their own reviews.

path Parameters
test_id
required
integer
Example: 1

test-id - id of a test execution

review_id
required
integer
Example: 1

unique ID of the review to update

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Request Body schema: application/json
priority
integer

priority, 0=lowest, 3=highest

entry
required
string

text of the review entry

reviewer
string or null

name of the reviewer

categories
string

whitespace separated list of categories

userAgent
string

user agent string

Responses

Request samples

Content type
application/json
{
  • "entry": "Updated booklet review",
  • "reviewer": "John Doe",
  • "priority": 2,
  • "categories": " tech",
  • "userAgent": "Mozilla/5.0..."
}

delete a booklet review

Deletes an existing review item for a booklet/test. Users can only delete their own reviews.

path Parameters
test_id
required
integer
Example: 1

test-id - id of a test execution

review_id
required
integer
Example: 1

unique ID of the review to delete

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Responses

add response to a unit

when running a test this endpoint is used to store given responses. Format and content of responses are business of the corresponding player, the endpoints take everything as raw, may it be JSON or XML or whatever.

path Parameters
test_id
required
string
Example: 1

test-id - id of a test execution.

unit_name
required
string
Example: UNIT.SAMPLE

unit-name (or alias) as defined in booklet

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Request Body schema: application/json
response
required
string

response data

timeStamp
required
integer

timestamp of the response

responseType
string

TODO what is this?

originalUnitId
string

original unit id, in case the unit id in the URL was overwritten by an alias

Responses

Request samples

Content type
application/json
{
  • "response": "I am the answers to your questions.",
  • "timeStamp": 1582550888563
}

save a state for a unit

Updates the state (a key-value list) of a unit in a running test with a given key-value pair. Some known state-keys are: - 'PRESENTATIONCOMPLETE' - 'RESPONSECOMPLETE' - 'PAGE_NR' - 'PAGE_COUNT' - 'PAGE_NAME' but all strings are allowed. For more about states see - https://github.com/iqb-berlin/testcenter/blob/master/frontend/src/app/test-controller/interfaces/test-controller.interfaces.ts - https://verona-interfaces.github.io/player/#operation-subscribe-vopStateChangedNotification

path Parameters
test_id
required
string
Example: 1

test-id - id of a test execution.

unit_name
required
string
Example: 1

unit-name (or alias) as defined in booklet

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Request Body schema: application/json
Array
key
required
string

The key of this state

content
required
string

The value of this state. For logs this is optional, since a log can be only a single string.

timeStamp
required
number

Because every state change gets logged a timestamp is necessary

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

update state of a running test

Updates the state (a key-value list) of a running test with a given key-value pair. Some known state-keys are: - 'CURRENT_UNIT' - 'CONTROLLER' but all strings are allowed. For more about states see - https://github.com/iqb-berlin/testcenter/blob/master/frontend/src/app/test-controller/interfaces/test-controller.interfaces.ts

path Parameters
test_id
required
string
Example: 1

test-id - id of a test execution.

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Request Body schema: application/json
Array
key
required
string

The key of this state

content
required
string

The value of this state. For logs this is optional, since a log can be only a single string.

timeStamp
required
number

Because every state change gets logged a timestamp is necessary

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

save a log-entry for a unit

Saves an array of log-entries for a unit in a running test. A log entry consists of a (JSON-encoded) content which is optional. Some currently used logentry key words for units are- UNITENTER, UNITTRYLEAVE, PRESENTATIONCOMPLETE, RESPONSESCOMPLETE, PAGENAVIGATIONSTART, PAGENAVIGATIONCOMPLETE.

path Parameters
test_id
required
string
Example: 1

test-id - id of a test execution.

unit_name
required
string
Example: UNIT.SAMPLE

unit-name (or alias) as defined in booklet

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Request Body schema: application/json
Array
key
required
string

The key of this state

content
string

The value of this state. For logs this is optional, since a log can be only a single string.

timeStamp
required
number

Because every state change gets logged a timestamp is necessary

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

save log-entries for a running test

Saves an array of log-entries for a running test. A log entry consists of a (JSON-encoded) content which is optional. Some currently used logentry key words for booklets are- BOOKLETLOADSTART, BOOKLETLOADCOMPLETE, BOOKLETLOCKEDbyTESTEE.

path Parameters
test_id
required
string
Example: 1

test-id - id of a test execution.

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Request Body schema: application/json
Array
key
required
string

The key of this state

content
string

The value of this state. For logs this is optional, since a log can be only a single string.

timeStamp
required
number

Because every state change gets logged a timestamp is necessary

Responses

Request samples

Content type
application/json
[
  • {
    }
]

finish a test

locks (finishes) a running test

path Parameters
test_id
required
string
Example: 1

test-id - id of a test execution.

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Request Body schema: application/json
message
required
string

message to log

timeStamp
required
integer

timestamp of locking event

Responses

Request samples

Content type
application/json
{
  • "timeStamp": 123456789,
  • "message": "test was locked"
}

start a test

Creates a new test for a given person and booklet-name

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Request Body schema: application/json
bookletName
required
string

name of the booklet to start

Responses

Request samples

Content type
application/json
{
  • "bookletName": "BOOKLET.SAMPLE-1"
}

Response samples

Content type
text/html;charset=utf-8
1

set command as executed

When the frontend executed a command, we send back this information to Backend via this command, to make sure it never gets executed again.

path Parameters
test_id
required
string
Example: 1

test-id - id of a test execution.

command_id
required
number
Example: 3

unique id of a command

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Responses

Notify Closing Test

A closing browser or such can use this window to notify, that a running test was closed. Because it has to be called under special circumstances, it does not need any authentication.

path Parameters
test_id
required
string
Example: 1

test-id - id of a test execution.

Responses

run monitor

get a group Deprecated

Retrieves Information about a (testtakers-)group. It has to be in the same workspace as the requesting user, who has to have in mode monitor-group or monitor-study.

path Parameters
group_name
required
string
Example: sample_group

name (id) of a group

header Parameters
AuthToken
required
any
Example: g:user000000000.0000000000

auth-token for group-monitor

Responses

Response samples

Content type
application/json
{
  • "label": "Primary Sample Group",
  • "name": "sample_group"
}

get TestSessions of a group

Retrieves all running test sessions all available groups of a monitor. Returns also an URL to a websocket to subscribe to this information if available. Sessions for Persons of this group which are not created right now get created.

header Parameters
AuthToken
required
any
Example: g:user000000000.0000000000

auth-token for group-monitor or study-monitor

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

get TestSessions of a group

Retrieves all running test sessions from specific group of a monitor. Returns also an URL to a websocket to subscribe to this information if available. Sessions for Persons of this group which are not created right now get created.

path Parameters
group_name
required
string
Example: sample_group

name (id) of a group

header Parameters
AuthToken
required
any
Examples:
  • g:user000000000.0000000000 -
  • s:user000000000.0000000000 -

auth-token for group-monitor or study-monitor

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

send command

Send a monitor command to a set of running tests

header Parameters
AuthToken
required
any
Example: g:user000000000.0000000000

auth-token for group-monitor

Request Body schema: application/json
keyword
string
arguments
Array of strings
timestamp
number

when the command was given

testIds
Array of integers

Responses

Request samples

Content type
application/json
{
  • "keyword": "MY-COMMAND",
  • "arguments": [
    ],
  • "timestamp": 1597906980,
  • "testIds": [
    ]
}

unlock a bunch of tests

Unlocks a bunch of running tests

path Parameters
group_name
required
string
Example: sample_group

name (id) of a group

header Parameters
AuthToken
required
any
Example: g:user000000000.0000000000

auth-token for group-monitor

Request Body schema: application/json
Array
number

Responses

Request samples

Content type
application/json
[
  • 2
]

Lock a bunch of tests

Locks a bunch of running tests

path Parameters
group_name
required
string
Example: sample_group

name (id) of a group

header Parameters
AuthToken
required
any
Example: g:user000000000.0000000000

auth-token for group-monitor

Request Body schema: application/json
Array
number

Responses

Request samples

Content type
application/json
[
  • 2
]

get the server time

return the server's current timestamp and timezone

Responses

Response samples

Content type
application/json
{
  • "timezone": "Europe/Berlin",
  • "timestamp": 1618816319707.522
}

set command as executed

When the frontend executed a command, we send back this information to Backend via this command, to make sure it never gets executed again.

path Parameters
test_id
required
string
Example: 1

test-id - id of a test execution.

command_id
required
number
Example: 3

unique id of a command

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Responses

get commands

Returns commands from the group-monitor (test-proctor) if given. They can be polled or subscribed via websocket if available. The websocket address is stored in header "SubscribeToken".

path Parameters
test_id
required
string
Example: 1

test-id - id of a test execution.

header Parameters
AuthToken
required
any
Example: p:0000000000000.00000000000

auth-token for test-user

Request Body schema: application/json
lastCommandId
integer

Optional. The id of a command. If given, only subsequent commands will be retrieved.

Responses

Request samples

Content type
application/json
{
  • "lastCommandId": 2
}

Response samples

Content type
application/json
[
  • {
    }
]

Notify Closing Test

A closing browser or such can use this window to notify, that a running test was closed. Because it has to be called under special circumstances, it does not need any authentication.

path Parameters
test_id
required
string
Example: 1

test-id - id of a test execution.

Responses

review

get all reviews of a person

Returns a Review report in JSON or CSV format for the person associated with the token. Uses the same format as workspace/{ws_id}/report/review with useNewVersion=true.

header Parameters
AuthToken
required
any
Example: p:a_person_token

auth-token for a person

Accept
any
Example: text/csv

Expected response Mimetype: 'text/csv' (the default) or 'application/json'

Responses

Response samples

Content type
"groupname";"loginname";"code";"bookletname";"unitname";"priority";"category_content";"reviewtime";"page";"pagelabel";"originalUnitId";"userAgent";"reviewer";"entry";"unitlabel";"bookletlabel"
"sample_group";"test";"xxx";"BOOKLET.SAMPLE-1";"UNIT.SAMPLE";"1";"TRUE";"2021-07-29 10:00:00";"1";"page-1";"UNIT.SAMPLE";"Firefox/126.0";;"mario: this is a sample unit review";"A Sample Unit to demonstrate the SamplePlayer2";"Sample booklet"
"sample_group";"test";"xxx";"BOOKLET.SAMPLE-1";"";"1";"TRUE";"2021-07-29 10:00:00";;;"";"Firefox/126.0";;"luigi: sample booklet review";"";"Sample booklet"

session management

Create Session Challenge

Creates a proof-of-work challenge for starting an Admin or Login session.

Request Body schema: application/json
required
loginType
required
string
Enum: "admin" "login"
name
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "loginType": "admin",
  • "name": "super",
  • "password": "user123"
}

Response samples

Content type
application/json
{
  • "algorithm": "SHA-1",
  • "challenge": "string",
  • "maxNumber": 0,
  • "salt": "string",
  • "signature": "string"
}

Create Person Session Challenge

Creates a proof-of-work challenge for starting a Person session with a code.

header Parameters
AuthToken
required
string
Example: l:user000000000.test0000000

Auth token for a Login session

Request Body schema: application/json
required
code
required
string

Responses

Request samples

Content type
application/json
{
  • "code": "xxx"
}

Response samples

Content type
application/json
{
  • "algorithm": "SHA-1",
  • "challenge": "string",
  • "maxNumber": 0,
  • "salt": "string",
  • "signature": "string"
}

get a session

Returns session data according to an authToken. ** Note, that it contains the relevant data twice, one time in the deprecated object access and one in the new form, claims. Don't use access, it will be removed.**

header Parameters
AuthToken
required
any
Examples:
  • p:0000000000000.00000000000 - auth-token for person
  • l:user000000000.test0000000 - auth-token for login (part I of 2-factor authorization only)
  • a:user000000000.rw00000000 - auth-token for admin

Responses

Response samples

Content type
application/json
Example
{
  • "token": "static:person:sample_group_test_xxx",
  • "displayName": "sample_group/test/xxx",
  • "claims": {
    },
  • "access": {
    },
  • "customTexts": { },
  • "flags": [ ]
}

Verify Challenge and create Session

Verifies a solved proof-of-work challenge and starts the requested session.

Request Body schema: application/json
required
algorithm
required
string
Enum: "SHA-1" "SHA-256" "SHA-512"
challenge
required
string
salt
required
string
signature
required
string
number
required
integer >= 0

Responses

Request samples

Content type
application/json
{
  • "algorithm": "SHA-256",
  • "challenge": "1ee58f58dca8fce65a63bdc02b3a2346e9c1fe7be4a2edf7593061a34c7c2f3f",
  • "salt": "000000000000000000000000?loginType=admin&name=super&password=user123&",
  • "signature": "aac6f23c76800951465f0dac364077d270f463659f8e8c0d79c51c3668bc047c",
  • "number": 0
}

Response samples

Content type
application/json
{
  • "token": "static:admin:super",
  • "displayName": "super",
  • "loginName": "super",
  • "groupLabel": null,
  • "id": 1,
  • "pwSetByAdmin": false,
  • "customTexts": { },
  • "flags": [ ],
  • "claims": {
    },
  • "groupToken": null,
  • "viewSettings": [ ],
  • "access": {
    }
}

delete a session

Performs a logout

header Parameters
AuthToken
required
any
Examples:
  • p:0000000000000.00000000000 - auth-token for person
  • l:user000000000.test0000000 - auth-token for login (part I of 2-factor authorization only)
  • a:user000000000.rw00000000 - auth-token for admin

Responses

Start Admin Session

Starts a Session as Admin by Username and password

Request Body schema: application/json
name
string

Username

password
string

Password

Responses

Request samples

Content type
application/json
{
  • "name": "super",
  • "password": "user123"
}

Response samples

Content type
application/json
{
  • "token": "user000000000.0000000000",
  • "displayName": "super",
  • "access": {
    }
}

Start Login Session

Starts a Session as Login to run a test by Username and password If the login requires a subsequent code insertion, you get a session with no access and the request for a password. Otherwise a set of accessible booklets will be retrieved.

Request Body schema: application/json
name
string

Username

password
string

Password

Responses

Request samples

Content type
application/json
{
  • "name": "test",
  • "password": "user123"
}

Response samples

Content type
application/json
{
  • "token": "static_login_sample_login",
  • "displayName": "sample_group/test",
  • "access": { },
  • "claims": { },
  • "customTexts": { },
  • "flags": [
    ]
}

Start Person Session

Starts a Session for a Person to run a test, on the basis of LoginToken (!) which is Part II of the Two-Factor Authentication for code-requiring logins. Get a token for a person belonging to a login, as defined in a Testtakers.xml-file, together with some information about this person

header Parameters
AuthToken
required
any
Example: l:user000000000.test0000000

auth-token for a login-session

Request Body schema: application/json
code
string

Responses

Request samples

Content type
application/json
{
  • "code": "xxx"
}

Response samples

Content type
application/json
{
  • "token": "static_person_xxx",
  • "displayName": "sample_group/test/xxx",
  • "loginName": "xxx",
  • "groupLabel": "sample_group",
  • "access": {
    },
  • "claims": {
    },
  • "customTexts": { },
  • "flags": [ ]
}

get a list of workspaces

get a list of all workspaces belonging to a given user

path Parameters
user_id
required
integer
Example: 1

user-id

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with super-admin privilege

Responses

Response samples

Content type
application/json
[
  • {
    }
]

get system check configuration

returns a specific SysCheck configuation this endpoint does not need any authetication!

path Parameters
ws_id
required
integer
Example: 1

workspace-id

sys_check_name
required
string
Example: SYSCHECK.SAMPLE

name of the SysCheck (as stored in the XML)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "label": "string",
  • "questions": [
    ],
  • "hasUnit": true,
  • "canSave": true,
  • "customTexts": { },
  • "skipNetwork": true,
  • "downloadSpeed": {
    },
  • "uploadSpeed": {
    },
  • "workspaceId": 0
}

run system check

download speedtest package

returns a byte package - for speedtests in system-check

path Parameters
size
required
string
Example: 16

number of bytes to be delivered - between 16 and 67108864

Responses

Response samples

Content type
text/plain;charset=utf-8
aaaaaaaaaaaaaaa=

upload speedtest package

receives any package and returns information about size and time - for speedtests in system-checks

Request Body schema: text/plain
string

Responses

Request samples

Content type
text/plain
1324567890123456

Response samples

Content type
application/json
{
  • "requestTime": 0,
  • "packageReceivedSize": 16
}

get a list of system checks

get a list of available SysChecks (from all workspaces)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

get system check Unit and Player

returns a container with the unit and it's player according to a SysCheck

path Parameters
ws_id
required
integer
Example: 1

workspace-id

sys_check_name
required
string
Example: SYSCHECK.SAMPLE

name of the SysCheck (as stored in the XML)

Responses

save system check

save the results of a performed SysCheck

path Parameters
ws_id
required
integer
Example: 1

workspace-id

sys_check_name
required
string
Example: SYSCHECK.SAMPLE

name of the SysCheck (as stored in the XML)

Request Body schema: application/json
Schema not provided

Responses

Request samples

Content type
application/json
{
  • "keyPhrase": "saveme",
  • "title": "dsk",
  • "environment": [
    ],
  • "questionnaire": [ ],
  • "unit": [
    ]
}

api info

Lists all available endpoints

Responses

Response samples

Content type
application/json
[
  • "[GET] /list/routes"
]

get system config

returns publicly available parts of system config - version number - customTexts for UI - uris of additional services - serverTimestamp (in milliseconds) - supported browsers - supported major versions of the XML schemas

Responses

Response samples

Content type
application/json
{
  • "version": "19.0.0",
  • "customTexts": { },
  • "appConfig": { },
  • "broadcastingServiceUri": "http://blabla",
  • "fileServiceUri": "http://blabla",
  • "veronaPlayerApiVersionMin": 2,
  • "veronaPlayerApiVersionMax": 4,
  • "xmlSchemaVersions": {
    },
  • "baseUrl": "http://testcenter.de",
  • "supportedBrowsers": [
    ],
  • "passwordMinLength": 7,
  • "passwordPattern": "^\\d+$"
}

get API version

Responses

Response samples

Content type
application/json
{
  • "version": "19.0.0"
}

super admin

get system config

returns publicly available parts of system config - version number - customTexts for UI - uris of additional services - serverTimestamp (in milliseconds) - supported browsers - supported major versions of the XML schemas

Responses

Response samples

Content type
application/json
{
  • "version": "19.0.0",
  • "customTexts": { },
  • "appConfig": { },
  • "broadcastingServiceUri": "http://blabla",
  • "fileServiceUri": "http://blabla",
  • "veronaPlayerApiVersionMin": 2,
  • "veronaPlayerApiVersionMax": 4,
  • "xmlSchemaVersions": {
    },
  • "baseUrl": "http://testcenter.de",
  • "supportedBrowsers": [
    ],
  • "passwordMinLength": 7,
  • "passwordPattern": "^\\d+$"
}

Update AppConfig

The AppConfig is a key-values store containing instance-specific settings for the frontend analogous to the CustomTexts, except that the values could be objects as well - they would become stringyfied then.

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with super-admin privilege

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "key": "value-pairs, values can be are",
  • "whatever": "you want",
  • "maybe": {
    },
  • "or": [
    ],
  • "even": null
}

Update CustomTexts

The CustomTexts is a key-values store containing instance-specific settings for the frontend analogous to the AppConfig. The Endpoint accepts anything as value, but CustomTexts should normally only contain string-values.

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with super-admin privilege

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "key": "value",
  • "another_key": "another_value"
}

get a list of workspaces

get a list of all workspaces

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with super-admin privilege

Responses

Response samples

Content type
application/json
[
  • {
    }
]

delete some workspaces

deletes a list of workspaces given by their ids. * requires the password of the performing user for security reasons

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with super-admin privilege

Request Body schema: application/json
ws
required
Array of integers

list of Workspace-Id

p
required
string

performing user's password

Responses

Request samples

Content type
application/json
{
  • "ws": [
    ],
  • "p": "user123"
}

get a list of users

returns info about all registered users.

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with super-admin privilege

Responses

Response samples

Content type
application/json
[
  • {
    }
]

delete some users

deletes a list of given user-ids. ids wich did not exist get skipped; in other words there is no check if the user exists beforeheand. * requires the password of the performing user for security reasons

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with super-admin privilege

Request Body schema: application/json
u
Array of strings
p
string

performing user's password

Responses

Request samples

Content type
application/json
{
  • "u": [
    ],
  • "p": "user123"
}

change user roles

changes user roles for a given user in several workspaces. Provide user-name, not user-id!

path Parameters
user_id
required
integer
Example: 1

user-id

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with super-admin privilege

Request Body schema: application/json
required
Array of objects

array of pairs role-id

Responses

Request samples

Content type
application/json
{
  • "ws": [
    ]
}

add a user

adds a user

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with super-admin privilege

Request Body schema: application/json
Schema not provided

Responses

Request samples

Content type
application/json
{
  • "n": "thirdUser",
  • "p": "thirdUsersPassword"
}

Response samples

Content type
text/html;charset=utf-8
1

change user-password

changes the password of a given user. Can be called by super admin for all other admins or by the affected workspace admins themselves. * if user_id is the performing user's own id (self-service change), oldPassword is required and is checked against the performing user's current password * if a super-admin resets another user's password, oldPassword is not required

path Parameters
user_id
required
integer
Example: 2

user-id

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with super-admin privilege

Request Body schema: application/json
p
string

the new password

oldPassword
string

the performing user's current password; required only for a self-service password change

Responses

Request samples

Content type
application/json
{
  • "p": "secondUsersNewPassword",
  • "oldPassword": "myCurrentPassword"
}

change super-admin status

changes the super-admin status of a given user. * requires a super-admin * requires the password of the performing user for security reasons * new_status is on or off

path Parameters
user_id
required
integer
Example: 2

user-id

new_status
required
string
Example: on

super-user status of the given user on or off

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with super-admin privilege

Request Body schema: application/json
p
string

performing user's password

Responses

Request samples

Content type
application/json
{
  • "p": "user123"
}

add a workspace

adds a workspace with given name

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with super-admin privilege

Request Body schema: application/json
name
required
string

workspace name

Responses

Request samples

Content type
application/json
{
  • "name": "new work space"
}

Response samples

Content type
text/html;charset=utf-8
3

get workspace Deprecated

returns basic information about a workspace

path Parameters
ws_id
required
integer
Example: 1

workspace-id

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with super-admin privilege

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "example_workspace",
  • "role": "RW"
}

rename a workspace

renames a workspace with given id

path Parameters
ws_id
required
integer
Example: 1

workspace-id

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with super-admin privilege

Request Body schema: application/json
name
string

Password

Responses

Request samples

Content type
application/json
{
  • "name": "a new york space"
}

change user roles

changes user roles in given workspaces

path Parameters
ws_id
required
integer
Example: 1

workspace-id

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with super-admin privilege

Request Body schema: application/json
required
Array of objects

array of pairs role-id

Responses

Request samples

Content type
application/json
{
  • "u": [
    ]
}

get a list of users in a workspace

returns info about all registered users in a workspace.

path Parameters
ws_id
required
integer
Example: 1

workspace-id

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with super-admin privilege

Responses

Response samples

Content type
application/json
[
  • {
    }
]

ask for system check

get info on weather the sys check menu should be shown on the login screen

get a boolean, showing weather this the system check menu is shown on the login screen

Responses

Response samples

Content type
application/json
true

get status information

Return information of additional services are configured and functioning.

Responses

Response samples

Content type
application/json
{
  • "broadcastingService": "string",
  • "fileService": "string",
  • "cacheService": "string"
}

workspace admin

change user-password

changes the password of a given user. Can be called by super admin for all other admins or by the affected workspace admins themselves. * if user_id is the performing user's own id (self-service change), oldPassword is required and is checked against the performing user's current password * if a super-admin resets another user's password, oldPassword is not required

path Parameters
user_id
required
integer
Example: 2

user-id

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with super-admin privilege

Request Body schema: application/json
p
string

the new password

oldPassword
string

the performing user's current password; required only for a self-service password change

Responses

Request samples

Content type
application/json
{
  • "p": "secondUsersNewPassword",
  • "oldPassword": "myCurrentPassword"
}

study monitor results

get study results without admin rights

retrieves a list of unit- and booklet results for a given workspace

path Parameters
ws_id
required
integer
Example: 1

id of a workspace

header Parameters
AuthToken
any
Example: s:user000000000.0000000000

auth-token for studyMonitor user containing a personToken

Responses

Response samples

Content type
application/json
[
  • {
    }
]

admin download

get file

retrieves a file form a given workspace by filename

path Parameters
ws_id
required
integer
Example: 1

workspace-id

type
required
string
Example: Unit

file type - Testtakers | Booklet | Resource | Unit | SysCheck - CASE SENSITIVE!

filename
required
string
Example: SAMPLE_UNIT.XML

filename. - CASE SENSITIVE!

header Parameters
required
object (auth)
Example: a:user000000000.ro00000000

auth-token for admin-user with role at least "RO" (read only) for this workspace

Responses

get report of logs

returns a Log report in JSON or CSV format based on aggregated unit and booklet log data

path Parameters
ws_id
required
integer
Example: 1

workspace-id

query Parameters
dataIds
Array of strings
Example: dataIds=review_group&dataIds=sample_group

a comma separated list of report data-ids

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with role at least "RO" (read only) for this workspace

Accept
any
Example: text/csv

Expected response Mimetype: 'text/csv' or 'application/json' (the default)

Responses

Response samples

Content type
"groupname";"loginname";"code";"bookletname";"unitname";"originalUnitId";"timestamp";"logentry"
"sample_group";"test";"xxx";"BOOKLET.SAMPLE-1";"UNIT.SAMPLE";"UNIT.SAMPLE";"1627545600000";"sample unit log"
"sample_group";"test";"xxx";"BOOKLET.SAMPLE-1";"";"";"1627545600000";"sample log entry"

get report of item responses

returns a Item Responses report in JSON or CSV format based on aggregated report data

path Parameters
ws_id
required
integer
Example: 1

workspace-id

query Parameters
dataIds
Array of strings
Example: dataIds=review_group&dataIds=sample_group

a comma separated list of report data-ids

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with role at least "RO" (read only) for this workspace

Accept
any
Example: text/csv

Expected response Mimetype: 'text/csv' or 'application/json' (the default)

Responses

Response samples

Content type
"groupname";"loginname";"code";"bookletname";"unitname";"originalUnitId";"responses";"laststate"
"sample_group";"test";"xxx";"BOOKLET.SAMPLE-1";"UNIT.SAMPLE";"UNIT.SAMPLE";"[{""id"":""1:UNIT.SAMPLE:v2"",""content"":""[{\""id\"":\""v2\"",\""value\"":[\""image:h5ki-bd-va4dg-jc2to2mp_6tga4teiw.png\""],\""status\"":\""VALUE_CHANGED\""}]"",""ts"":1627545600000,""responseType"":""iqb-standard@1.0""},{""id"":""all"",""content"":""{\""name\"":\""Sam Sample\"",\""age\"":34}"",""ts"":1627545600000,""responseType"":""example-data-format""}]";"{""PRESENTATIONCOMPLETE"": ""yes""}"

get report of item reviews

returns a Review report in JSON or CSV format based on aggregated unit and booklet review data

path Parameters
ws_id
required
integer
Example: 1

workspace-id

query Parameters
dataIds
Array of strings
Example: dataIds=review_group&dataIds=sample_group

a comma separated list of report data-ids

useNewVersion
string
Examples:
  • useNewVersion=false - old format
  • useNewVersion=true - new format

triggers the new enhanced format of reviews. set to true or false (false is default)

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with role at least "RO" (read only) for this workspace

Accept
any
Example: text/csv

Expected response Mimetype: 'text/csv' or 'application/json' (the default)

Responses

Response samples

Content type
Example
"groupname";"loginname";"code";"bookletname";"unitname";"priority";"category: content";"reviewtime";"entry";"page";"pagelabel";"originalUnitId";"userAgent"
"sample_group";"test";"xxx";"BOOKLET.SAMPLE-1";"UNIT.SAMPLE";"1";"X";"2021-07-29 10:00:00";"mario: this is a sample unit review";"1";"page-1";"UNIT.SAMPLE";"Firefox/126.0"
"sample_group";"test";"xxx";"BOOKLET.SAMPLE-1";"";"1";"X";"2021-07-29 10:00:00";"luigi: sample booklet review";;;"";"Firefox/126.0"

get report of system checks

returns a System Check report in JSON or CSV format based on aggregated report data

path Parameters
ws_id
required
integer
Example: 1

workspace-id

query Parameters
dataIds
Array of strings
Example: dataIds=SYSCHECK.SAMPLE

a comma separated list of report data-ids

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with role at least "RO" (read only) for this workspace

Accept
any
Example: text/csv

Expected response Mimetype: 'text/csv' or 'application/json' (the default)

Responses

Response samples

Content type
"Titel";"SysCheck-Id";"SysCheck";"Responses";"DatumTS";"Datum";"FileName";"Betriebssystem";"Betriebssystemversion";"Bildschirmauflösung";"Browser";"Browser-Cookies aktiviert";"Browser-Plugins";"Browsersprache";"Browserversion";"CPU-Architektur";"CPU-Kerne";"Fenstergröße";"Downloadgeschwindigkeit";"Downloadgeschwindigkeit benötigt";"Downloadbewertung";"Uploadgeschwindigkeit";"Uploadgeschwindigkeit benötigt";"Uploadbewertung";"Gesamtbewertung";"RoundTrip in ms";"Netzwerktyp nach Leistung";"Downlink MB/s";"Name";"Who am I?";"Why so serious?";"Check this out";"All we here is";"loading time"
"SAMPLE SYS-CHECK REPORT";"SYSCHECK.SAMPLE";"An example SysCheck definition";"";"1627545600";"2021-07-29 10:00:00";"SAMPLE_SYSCHECK-REPORT.JSON";"Linux";"x86_64";"1680 x 1050";"Chrome";"1";"Chromium PDF Plugin, Chromium PDF Viewer";"en-US";"79";"amd64";"8";"1680 x 914";"75.72 Mbit/s";"8.19 kbit/s";"good";"2.84 Mbit/s";"8.19 kbit/s";"good";"good";"100";"4g";"1.45";"Sam Sample";"Harvy Dent";"Because.";"1";"Radio Gaga";"1594.295166015625"

admin workspace

delete data

deletes all results and monitor data of a group of groups

path Parameters
ws_id
required
integer
Example: 1

workspace-id

header Parameters
AuthToken
required
any
Example: a:user000000000.rw00000000

auth-token for admin-user with role "RW" (read/write) for this workspace

Request Body schema: application/json
groups
Array of strings

array of group names

Responses

Request samples

Content type
application/json
{
  • "groups": [
    ]
}

get test sessions with state grouped by group

retrieves test sessions with non-empty laststate for a given workspace, grouped by group names

path Parameters
ws_id
required
integer
Example: 1

workspace-id

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with role at least "RO" (read only) for this workspace

Responses

Response samples

Content type
application/json
{
  • "sample_group": [
    ]
}

delete responses for specific person sessions

deletes all response data for specific person sessions (identified by login name + person code combinations)

path Parameters
ws_id
required
integer
Example: 1

workspace-id

header Parameters
AuthToken
required
any
Example: a:user000000000.rw00000000

auth-token for admin-user with role "RW" (read/write) for this workspace

Request Body schema: application/json
required
Array of objects

array of person session identifiers (login name + code combinations)

Responses

Request samples

Content type
application/json
{
  • "personSessions": [
    ]
}

get results

retrieves a list of unit- and booklet results for a given workspace and groups

path Parameters
ws_id
required
integer
Example: 1

workspace-id

query Parameters
groups
string
Example: groups=sample_group,review_group

comma-separated list of group names to filter results by

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with role at least "RO" (read only) for this workspace

Responses

Response samples

Content type
application/json
[
  • {
    }
]

get files of workspace

get a list of all files in workspace

path Parameters
ws_id
required
integer
Example: 1

workspace-id

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with role at least "RO" (read only) for this workspace

Responses

Response samples

Content type
application/json
{
  • "Booklet": [
    ],
  • "SysCheck": [
    ],
  • "Testtakers": [
    ],
  • "Unit": [
    ],
  • "Resource": [
    ]
}

delete files

deletes files from a workspace

path Parameters
ws_id
required
integer
Example: 1

workspace-id

header Parameters
AuthToken
required
any
Example: a:user000000000.rw00000000

auth-token for admin-user with role "RW" (read/write) for this workspace

Request Body schema: application/json
f
Array of strings

array of file names

Responses

Request samples

Content type
application/json
{
  • "f": [
    ]
}

Response samples

Content type
application/json
{
  • "deleted": [
    ],
  • "did_not_exist": [
    ],
  • "not_allowed": [
    ],
  • "was_used": [
    ]
}

get files with respective dependencies of workspace

get a list of all files with their in workspace

path Parameters
ws_id
required
integer
Example: 1

workspace-id

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with role at least "RO" (read only) for this workspace

Request Body schema: application/json
body
Array of strings

array of file names

Responses

Request samples

Content type
application/json
{
  • "body": [
    ]
}

Response samples

Content type
application/json
{
  • "Booklet": [
    ],
  • "SysCheck": [
    ],
  • "Testtakers": [
    ],
  • "Unit": [
    ],
  • "Resource": [
    ]
}

delete system check reports

deletes some System Check reports

path Parameters
ws_id
required
integer
Example: 1

workspace-id

header Parameters
AuthToken
required
any
Example: a:user000000000.rw00000000

auth-token for admin-user with role "RW" (read/write) for this workspace

Request Body schema: application/json
checkIds
required
Array of strings

array of sys-check-Ids

Responses

Request samples

Content type
application/json
{
  • "checkIds": [
    ]
}

Response samples

Content type
application/json
{
  • "deleted": [
    ],
  • "did_not_exist": null,
  • "not_allowed": null,
  • "was_used": null
}

get a list of all system check reports

returns a list of all sys-check-reports with most important features grouped by the sys-checks.

path Parameters
ws_id
required
integer
Example: 1

workspace-id

header Parameters
AuthToken
required
any
Example: a:user000000000.superadmin0

auth-token for admin-user with role at least "RO" (read only) for this workspace

Responses

Response samples

Content type
application/json
[
  • {
    }
]

admin upload

upload file

Uploads a Resource, Unit, Booklet, SysCheck or Testtakers file. The File gets imported to the workspace if it is valid, and passes the cross-validation checks. So a file which depends of a non-existing player will get rejected as well as an invalid xml file.

When a file with the same filename and type exists in the workspace, it gets overwritten! Except if the internal id (the -Tag as used in Unit-files for example) of the old and the new file differs. In this case it's assumed, that the file-name-duplication is inintentional and the new import gets rejected.

The endpoint accepts all kinds of files. Zip-archives get extracted an treated the same as multi-file-upload.

path Parameters
ws_id
required
integer
Example: 1

workspace-id

header Parameters
AuthToken
required
any
Example: a:user000000000.rw00000000

auth-token for admin-user with role "RW" (read/write) for this workspace

Request Body schema: multipart/form-data
fileforvo
required
string

upload file

Responses

Response samples

Content type
application/json
{
  • "SAMPLE_UNIT.XML": {
    }
}