Backend API

Contents:

• General
• All Users
  • PING
  • GET_FILTERS_DATA
• Experimenter
  • GET_SESSION_LIST
  • SAVE_SESSION
  • DELETE_SESSION
  • CREATE_EXPERIMENT
  • JOIN_EXPERIMENT
  • LEAVE_EXPERIMENT
  • START_EXPERIMENT
  • STOP_EXPERIMENT
  • ADD_NOTE
  • CHAT
  • KICK_PARTICIPANT
  • BAN_PARTICIPANT
  • MUTE
  • SET_FILTERS
  • SET_GROUP_FILTERS
  • GET_FILTERS_DATA_SEND_TO_PARTICIPANT
  • GET_FILTERS_CONFIG
• Participant
  • CHAT

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

Type	Data
PONG	Pong JSON

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

Type	Data
GET_FILTERS_DATA	GetFiltersDataRequest JSON

Response

Type	Data
FILTERS_DATA	dict of [str, FiltersData] JSON

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.

Type	Data
SAVED_SESSION	Session JSON
SESSION_CHANGE	Session JSON

DELETE_SESSION

Description

Permanently delete a session on the server.

Request

Type	Data
DELETE_SESSION	SessionIdRequest JSON

Response

The response contains the id of the deleted session and is broadcasted to all experimenters.

Type	Data
DELETED_SESSION	SessionIdRequest JSON

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

Type	Data
CREATE_EXPERIMENT	SessionIdRequest JSON

Response

If successful, the backend sends a EXPERIMENT_CREATED message to all experimenters and a JOIN_EXPERIMENT to the caller.

Type	Data
JOIN_EXPERIMENT	Success JSON
EXPERIMENT_CREATED	SessionIdRequest JSON

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

Type	Data
JOIN_EXPERIMENT	SessionIdRequest JSON

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

Type	Data
ADD_NOTE	Success JSON

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

Type	Data
CHAT	ChatMessage JSON

• author must be experimenter

Response

Type	Data
CHAT	Success JSON

KICK_PARTICIPANT

Description

Kick a participant in the current experiment. Use CREATE_EXPERIMENT or JOIN_EXPERIMENT to connect to an experiment.

Request

Type	Data
KICK_PARTICIPANT	KickRequest JSON

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

Type	Data
BAN_PARTICIPANT	KickRequest JSON

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

Type	Data
MUTE	MuteRequest JSON

Response

Type	Data
MUTE	Success JSON

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

Type	Data
SET_FILTERS	SetFiltersRequest JSON

Response

Type	Data
SET_FILTERS	Success JSON
SESSION_CHANGE	Session JSON

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

Type	Data
SET_GROUP_FILTERS	SetGroupFiltersRequest JSON

Response

Type	Data
SET_GROUP_FILTERS	Success JSON
SESSION_CHANGE	Session JSON

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

Type	Data
GET_FILTERS_DATA_SEND_TO_PARTICIPANT	GetFiltersDataSendToParticipantRequest JSON

Response

Type	Data
FILTERS_DATA	dict of [str, FiltersData] JSON

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

Type	Data
FILTERS_CONFIG	FilterConfigDict

Participant

CHAT

Description

Send a chat message to the experimenters connected to the experiment the participant is part of.

Request

Type	Data
CHAT	ChatMessage JSON

• target must be experimenter
• author must be the participant ID

Response

Type	Data
CHAT	Success JSON