WebSocket API (WIP)

Usage in NodeJS

This page is a Work in progress, not everything will be complete or up to date.

Add socket.io-client library

npm i socket.io-client

const { io } = require('socket.io-client');

Set up constants

Set the address for the FormbarJS instance you wish to connect to, and your API Key...

const FORMBAR_URL = 'http://172.16.3.159:420/';
const API_KEY = 'get ur own api key and put it here';

You can get your API key by logging into the instance of FormbarJS you wish to interact with and going to /apikey.

Prepare socket for API calls

Set the Formbar url and api key with this. This will also try to connect to the Formbar.

const socket = io(FORMBAR_URL, {
	extraHeaders: {
		api: API_KEY
	}
});

Connect to the Formbar

Do this to detect when you connect

socket.on('connect', () => {
	console.log('connected');
	// This will get the class you are logged into.
	socket.emit('getUserClass', { api: API_KEY });
});

This will check if there is a connection error and attempt to reconnect in 5 seconds.

socket.on('connect_error', (error) => {
	/*
		"xhr poll error" is just the error it give when it can't connect,
		which is usually when the Formbar is not on or you are not on the same network.
	*/
	if (error.message == 'xhr poll error') console.log('no connection');
	// This is an error from the Formbar such as "not a valid API key".
	else console.log(error.message);

	setTimeout(() => {
		socket.connect();
	}, 5000);
});

This happens when Formbar sends your class back. If there is an error it will log it and try again in 5 seconds. If there is not an error and it returns your class it will join your class.

socket.on('getUserClass', (userClass) => {
	if (userClass.error) {
		console.log(userClass.error);
		setTimeout(() => {
			socket.emit('getUserClass', { api: API_KEY });
		}, 5000);
	} else if (userClass) {
		classCode = userClass;
		socket.emit('joinRoom', classCode);
	}
});

When the class ends, it leaves the class, and attempts to get your class again.

socket.on('classEnded', () => {
	socket.emit('leave', classCode);
	classCode = '';
	socket.emit('getUserClass', { api: API_KEY });
});

Make the a request

Emit the data you are trying to get when you join the class. In this example I will be using vbUpdate.

socket.on('joinRoom', (classCode) => {
	if (classCode) {
		socket.emit('vbUpdate');
	}
});

This is how you get the data after you request it.

socket.on('vbUpdate', (data) => {
	console.log(data);
});

API

Authentication

Requires api in header

Permissions

Permissions are in order from highest to least permissions.

Manager - 5
Teacher - 4
Mod - 3
Student - 2
Guest - 1
Banned - 0

Returnable Objects

Student

Username: {
    "loggedIn": Boolean,
    "username": String,
    "id": Integer,
    "permissions": Integer,
    "help": String,
    "break": String,
    "quizScore": String
}

Poll

Key: {
    "display": String,
    "responses": Integer
    "color": HexString
}

Help

"reason": String,
"time": {
	"hours": Integer,
	"minutes": Integer,
	"seconds": Integer
}

Endpoints

Me

Shows the user's data based on your API key.

URL

GET /me

Authentication

Any permission level.

Response

Parameter	Type	Permissions	Description
loggedIn	Boolean	Any	Indicates whether the user is currently logged in or not. A value of true means the user is logged in, while false means the user is not logged in.
id	Integer	Any	The unique identifier for the user. This could be used to reference the user in other parts of the system.
username	String	Any	The username of the user. This is typically used for display purposes and may also be used for identification in some systems.
permissions	Integer	Any	The permissions level of the user. This could be used to control what actions the user is allowed to perform in the system.
classPermissions	Integer	Any	The permissions level of the user within a specific class or course. This could be used to control what actions the user is allowed to perform within a specific class.
help	help | False | Null	Any	If there is no help ticket, the value of help will be null. If there is a help ticket, the value of help will be an object that represents the help ticket. For more details about the structure of the help object, please refer to the Help object documentation.
break	String | Boolean | Null	Any	If the user is logged out, the value of break will be null. If the user is logged in and not on break, the value of break will be false. If the user is logged in and on break, the value of break will be true. If the user is logged in and a break request is being processed, the value of break will be a string that describes the break request.
quizScore	String | Null	Any	If the user is logged out, the value of quizScore will be null. If the user is logged in and has not taken a quiz, the value of quizScore will be an empty string. If the user is logged in and has taken a quiz, the value of quizScore will be a string that represents the user's score from the quiz. The score will be in the format "your score/total score".
pogMeter	Integer | Null	Any	If the user is logged out, the value of pogMeter will be null. If the user is logged in and has not answered a question correctly, the value of pogMeter will be an empty string. If the user is logged in and has answered a question correctly, the value of pogMeter will be an integer that represents the user's progress towards the next digipog.

Class

Shows class's data.

URL

GET /class/{classCode}

Authentication

You must be a student and logged into the class.

Response

Parameter	Type	Permissions	Description
id	Integer	Student	The unique identifier of the class.
className	String	Student	The name of the class.
students	Object	loggedIn: Requires student permissions. id: Requires student permissions. username: Requires student permissions. permissions: Requires mod permissions. classPermissions: Requires mod permissions. help: Requires mod permissions. When mod, you can only see if there is a help ticket. Teachers can see the Help object. break: Requires mod permissions. When mod, you can only see if they are on break. Teachers can see the reason. quizScore: Requires mod permissions. pogMeter: Requires mod permissions.	An object containing the data of each student in the class. Each key in the object is the student's username, and the value is the student's data. For more details about the structure of the student object, refer to the student object.
poll	Object	Student	An object representing the current poll. For more information refer to the poll object
key	String	Student
lesson	Object	Student	An object representing the current lesson.
activeLesson	Boolean	Student	A boolean value indicating whether there is an active lesson.
currentStep	Integer	Student	An integer representing the current step of the lesson.
quiz	Boolean	Student	A boolean value indicating whether there is a quiz.
mode	String	Student	A string representing the current mode, which could be poll, quiz, lesson, or game.

Students

Shows all of a class's students.

URL

GET /class/{classCode}/students

Authentication

You must be a student and logged into the class.

Response

Parameter	Type	Permissions	Description
students	Object	loggedIn: Requires student permissions. id: Requires student permissions. username: Requires student permissions. permissions: Requires mod permissions. classPermissions: Requires mod permissions. help: Requires mod permissions. When mod, you can only see if there is a help ticket. Teachers can see the Help object. break: Requires mod permissions. When mod, you can only see if they are on break. Teachers can see the reason. quizScore: Requires mod permissions. pogMeter: Requires mod permissions.	refer to student object

Class Poll

Show a class's polls

Authentication

You must be logged into the class.

URL

GET /class/{classCode}/poll

Response

Parameter	Type	Permissions	Description
status	Boolean	Any	Indicates the current status of the poll. A value of true means a poll is active, while false means no poll is not active.
totalStudents	Integer	Any	Represents the total number of students in the class.
pollPrompt	String	Any	The prompt or question of the current poll.
blindPoll	Boolean	Any	Indicates whether the poll is a blind poll. A value of true means the poll is blind (students can't see others' responses), while false means the poll is not blind.
weight	Boolean	Any	Indicates the weight of the poll. This value represents the contribution of the poll towards the final quiz score and pog meter.
polls	poll object.	Any	An object that represents the current polls. Each key in the object is a possible response to the poll, and the value is the number of students who responded with that response. For more details about the structure of the polls object, please refer to the poll object documentation.