API: Difference between revisions

From Resonite Wiki
Add SignalR section
Line 14: Line 14:




To get a token, send a POST request to https://api.resonite.com/userSessions with the following body:
To get a token, send a POST request to <code><nowiki>https://api.resonite.com/userSessions</nowiki></code> with the following body:
<syntaxhighlight lang="json">
<syntaxhighlight lang="json">
{
{
Line 40: Line 40:


The API should respond with a JSON object containing information about the created user-session, most importantly the token used for authentication as well as your user-id.
The API should respond with a JSON object containing information about the created user-session, most importantly the token used for authentication as well as your user-id.
== SignalR ==
The Resonite API uses the [[wikipedia:SignalR|SignalR]] protocol for server-driven notifications such as informing the client of new chat messages or status changes. Internally this is simply a WebSocket connection between the Resonite client and API SignalR Hub with some additional control messages. Most modern programming languages should have libraries for SignalR available, however if they do not, the protocol is [https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/HubProtocol.md well documented] and can be easily emulated.
The hub address is <code><nowiki>https://api.resonite.com/hub</nowiki></code>, or if you're creating a WebSocket connection manually <code>wss://api.resonite.com/hub</code>.
To authenticate with the hub, the same Authorization header as specified above is required.
=== Functions ===
The following server side functions are available
===== SendMessage =====
===== MarkMessagesRead =====
===== BroadcastStatus =====
===== UpdateContact =====
===== ListenOnContact =====
===== ListenOnKey =====
===== RequestStatus =====
===== InitializeStatus =====
===== BroadcastSession =====
===== BroadcastSessionEnded =====

Revision as of 13:55, 13 January 2024

Documentation for the Resonite API which can be used by external apps to communicate with Resonite.

This documentation is unofficial and incomplete and may break at any time.

The main API URL is https://api.resonite.com/

Authentication

Many endpoints of the Resonite API require authentication by means of an authorization token.

This token needs to be sent as a Authorization HTTP request header on endpoints that require it:

Authorization: res <user-id>:<token>

Note that user-id is not the same as your username. Migrated accounts may have user-ids that are similar to their username, but newly created accounts will get a random user-id assigned to them. User-ids always start with U-.


To get a token, send a POST request to https://api.resonite.com/userSessions with the following body:

{
    "username": "<username>",
    "authentication": {
        "$type" : "password",
        "password": "<password>"
    },
    "secretMachineId": "<secret-machine-id>",
    "rememberMe": true
}
  • username and password are your account credentials. DO NOT replace the "password" specifier in the "$type" field.
  • secretMachineId can be a random UUIDv4
  • The rememberMe flag determines how long the resulting token will be valid. If it is set to true, the token will be valid for 30 days.

This authentication request also needs additional headers:

UID: <uid>
TOTP: <totp>
  • UID should be a sha256 hash based on information about the hardware this request was sent from, so every device that connects to the API should have its own unique string that never changes. You can however just use any random sha256 hash if you do not want to generate it specifically for your hardware.
  • TOTP is a four number code generated by your two-factor authentication (2FA) application of choice and only needs to be sent if 2FA is enabled for your user account.

The API should respond with a JSON object containing information about the created user-session, most importantly the token used for authentication as well as your user-id.

SignalR

The Resonite API uses the SignalR protocol for server-driven notifications such as informing the client of new chat messages or status changes. Internally this is simply a WebSocket connection between the Resonite client and API SignalR Hub with some additional control messages. Most modern programming languages should have libraries for SignalR available, however if they do not, the protocol is well documented and can be easily emulated.

The hub address is https://api.resonite.com/hub, or if you're creating a WebSocket connection manually wss://api.resonite.com/hub.

To authenticate with the hub, the same Authorization header as specified above is required.

Functions

The following server side functions are available

SendMessage
MarkMessagesRead
BroadcastStatus
UpdateContact
ListenOnContact
ListenOnKey
RequestStatus
InitializeStatus
BroadcastSession
BroadcastSessionEnded