Contents:
General
- API endpoints depend on the user type. Endpoints available for experimenters are listed in the Experimenter section, endpoints for participants in Participant. Endpoints in All Users are exempt from this and available to all users.
- The following endpoints refer to the API provided over the WebRTC data channels.
- All requests are made using Message JSONs.
- Besides the responses listed bellow, all endpoint responses also include:
type
ERROR, data: Error JSON.
All Users
PING
Description
Send a echo request / ping message. Server will respond with a pong message including the original data from the ping as well as a server timestamp.
Request
| Type |
Data |
PING |
{ ...optional arbitrary data } |
Response
GET_FILTERS_DATA
Description
Get all data for a requested filter (match filter name, channel and id) for all participants or only a specific (if request is made from Participant side). Server will respond with a message that contains all data of a filter.
If you want to receive data from a filter, the filter itself needs to implement the get_filter_data method.
BE CAUTIOUS: call from participant does not work (look at issue 154)
Request
Response
Experimenter
GET_SESSION_LIST
Description
Get all sessions saved on the server.
Request
| Type |
Data |
GET_SESSION_LIST |
{} |
Response
| Type |
Data |
SESSION_LIST |
List of Session JSONs |
SAVE_SESSION
Description
Save a session JSON on the server. Can be a new session (without any ID's) or an updated session (with session_id).
Request
| Type |
Data |
SAVE_SESSION |
Session JSON |
Response
A SAVED_SESSION message is send to the caller and SESSION_CHANGE to all other experimenters connected to the hub.
DELETE_SESSION
Description
Permanently delete a session on the server.
Request
Response
The response contains the id of the deleted session and is broadcasted to all experimenters.
CREATE_EXPERIMENT
Description
Create an experiment based on a session stored in the backend.
The experiment will be in waiting state and participants can join.
If successful, a EXPERIMENT_CREATED message will be send to all experimenters connected to the hub.
Request
Response
If successful, the backend sends a EXPERIMENT_CREATED message to all experimenters and a JOIN_EXPERIMENT to the caller.
JOIN_EXPERIMENT
Description
Join an existing experiment.
Required for other API calls, that interact with an experiment. E.g. START_EXPERIMENT and STOP_EXPERIMENT.
Request
Response
| Type |
Data |
JOIN_EXPERIMENT |
Success JSON |
LEAVE_EXPERIMENT
Description
Leave the experiment the experimenter is currently connected to. Returns an error if not connected to an experiment.
Request
| Type |
Data |
LEAVE_EXPERIMENT |
{} |
Response
| Type |
Data |
LEAVE_EXPERIMENT |
Success JSON |
START_EXPERIMENT
Description
Start the experiment the experimenter is currently connected to.
Use CREATE_EXPERIMENT or JOIN_EXPERIMENT to connect to an experiment.
If successful, a EXPERIMENT_STARTED message will be send to all experimenters connected to the experiment.
Request
| Type |
Data |
START_EXPERIMENT |
{} |
Response
| Type |
Data |
START_EXPERIMENT |
Success JSON |
STOP_EXPERIMENT
Description
Stop the experiment the experimenter is currently connected to.
Use CREATE_EXPERIMENT or JOIN_EXPERIMENT to connect to an experiment.
If successful, a EXPERIMENT_ENDED message will be send to all experimenters connected to the experiment.
Request
| Type |
Data |
STOP_EXPERIMENT |
{} |
Response
| Type |
Data |
STOP_EXPERIMENT |
Success JSON |
ADD_NOTE
Description
Add a note to the experiment the experimenter is currently connected to.
Use CREATE_EXPERIMENT or JOIN_EXPERIMENT to connect to an experiment.
Request
| Type |
Data |
ADD_NOTE |
Note JSON |
Response
CHAT
Description
Send a chat message to all or a single participant in the experiment the experimenter is currently connected to.
Use CREATE_EXPERIMENT or JOIN_EXPERIMENT to connect to an experiment.
Request
author must be experimenter
Response
KICK_PARTICIPANT
Description
Kick a participant in the current experiment.
Use CREATE_EXPERIMENT or JOIN_EXPERIMENT to connect to an experiment.
Request
Response
| Type |
Data |
KICK_PARTICIPANT |
Success JSON |
BAN_PARTICIPANT
Description
Ban a participant in the current experiment.
Use CREATE_EXPERIMENT or JOIN_EXPERIMENT to connect to an experiment.
Request
Response
| Type |
Data |
BAN_PARTICIPANT |
Success JSON |
MUTE
Description
Set the muted state for a participant in the current experiment.
Use CREATE_EXPERIMENT or JOIN_EXPERIMENT to connect to an experiment.
Request
Response
SET_FILTERS
Description
Modify the filters for a participant in the current experiment. See SetFiltersRequest for details about the request contents.
A SUCCESS message is send to the caller and SESSION_CHANGE to all experimenters connected to the hub.
Request
Response
SET_GROUP_FILTERS
Description
Modify the group filters for the experiment. See SetGroupFiltersRequest for details about the request contents.
A SUCCESS message is send to the caller and SESSION_CHANGE to all experimenters connected to the hub.
Request
Response
GET_FILTERS_DATA_SEND_TO_PARTICIPANT
Description
Sends a message to the participants or only a specific participant. The server collects all statuses for the requested filter (match filter name, channel and id)
If you want to receive data from a filter, the filter itself needs to implement the get_filter_data method.
Request
Response
GET_FILTERS_CONFIG
Description
This API call gets all the filters configurations which means how dynamic filters are implemented in frontend. It retuns an object of Filter arrays
Request
| Type |
Data |
GET_FILTERS_CONFIG |
{} |
Response
Participant
CHAT
Description
Send a chat message to the experimenters connected to the experiment the participant is part of.
Request
target must be experimenterauthor must be the participant ID
Response