BareRTC/docs/API.md

BareRTC Web API

BareRTC provides some web API endpoints over HTTP to support better integration with your website.

Authentication to the API endpoints is gated by the AdminAPIKey value in your settings.toml file.

For better integration with your website, the chat server exposes some data via JSON APIs ready for cross-origin ajax requests. In your settings.toml set the CORSHosts to your list of website domains, such as "https://www.example.com", "http://localhost:8080" or so on.

Current API endpoints include:

GET /api/statistics

Returns basic info about the count and usernames of connected chatters:

{
    "UserCount": 1,
    "Usernames": ["admin"]
}

POST /api/authentication

This endpoint can provide JWT authentication token signing on behalf of your website. The Chatbot program calls this endpoint for authentication.

Post your desired JWT claims to the endpoint to customize your user and it will return a signed token for the WebSocket protocol.

{
	"APIKey": "from settings.toml",
	"Claims": {
		"sub": "username",
		"nick": "Display Name",
		"op": false,
		"img": "/static/photos/avatar.png",
		"url": "/users/username",
		"emoji": "🤖",
		"gender": "m"
	}
}

The return schema looks like:

{
	"OK": true,
	"Error": "error string, omitted if none",
	"JWT": "jwt token string"
}

POST /api/shutdown

Shut down (and hopefully, reboot) the chat server. It is equivalent to the /shutdown operator command issued in chat, but callable from your web application. It is also used as part of deadlock detection on the BareBot chatbot.

It requires the AdminAPIKey to post:

{
	"APIKey": "from settings.toml"
}

The return schema looks like:

{
	"OK": true,
	"Error": "error string, omitted if none"
}

The HTTP server will respond OK, and then shut down a couple of seconds later, attempting to send a ChatServer broadcast first (as in the /shutdown command). If the chat server is deadlocked, this broadcast won't go out but the program will still exit.

It is up to your process supervisor to automatically restart BareRTC when it exits.

POST /api/blocklist

Your server may pre-cache the user's blocklist for them before they enter the chat room. Your site will use the AdminAPIKey parameter that matches the setting in BareRTC's settings.toml (by default, a random UUID is generated the first time).

The request payload coming from your site will be an application/json post body like:

{
    "APIKey": "from your settings.toml",
    "Username": "soandso",
    "Blocklist": [ "usernames", "that", "they", "block" ],
}

The server holds onto these in memory and when that user enters the chat room (JWT authentication only) the front-end page will embed their cached blocklist. When they connect to the WebSocket server, they send a blocklist message to push their blocklist to the server -- it is basically a bulk mute action that mutes all these users pre-emptively: the user will not see their chat messages and the muted users can not see the user's webcam when they broadcast later, the same as a regular mute action.

The JSON response to this endpoint may look like:

{
    "OK": true,
    "Error": "if error, or this key is omitted if OK"
}