API

From Resonite Wiki
Revision as of 18:15, 14 October 2024 by Brodokk (talk | contribs) (→‎GET /platform: Clarify authentication support and typo)
Resonite's API is a heavy WIP, we offer no support or guarantees regarding any Endpoint, Model or functionality. Things may change at any time.

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

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-.

Creating a token

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. If you need to invalidate the token before that (such as if the token is leaked), please see revoking a token.

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.

Revoking a token

To revoke a token, send a DELETE request to https://api.resonite.com/userSessions/{userId}/{token_to_be_revoked} with an authorization header. Please note that the token used in the authorization header does not need to match the token specified in the URL.

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 your language of choice does 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 in Authentication is required.

If you are working with a programming language without a SignalR library, manual testing connection can be made with websocat for example like so: 

websocat -H="Authorization: res U-username:token=" wss://api.resonite.com/hub

after which the SignalR protocol negotiation can be completed by sending a simple JSON snippet with a special U+001E line ending delimiter (missing from the following example due to UTF-8 stripping on the wiki):

{"protocol":"json","version":1}

Functions

The following server side functions are available:

SendMessage

MarkMessagesRead

BroadcastStatus

UpdateContact

ListenOnContact

ListenOnKey

RequestStatus

InitializeStatus

BroadcastSession

BroadcastSessionEnded

Events

The following events can be sent by the server (this list may be incomplete):

MessageSent

ReceiveMessage

MessagesRead

ReceiveSessionUpdate

RemoveSession

ReceiveStatusUpdate

Endpoints

Sessions

GET /sessions/{sessionId}

Returns the Session object for the session specified by {sessionId}, provided it is a publicly accessible session.

Does not require authentication.

GET /sessions

Returns a list of public sessions filtered by the given parameters.

Does not require authentication

URL parameters:

  • compatibilityHash: The compatibility-hash sessions needs to have. A Resonite client can only join a session if this hash matches between client and server. (string, optional)
  • name: The session name to search for. (string, optional)
  • universeId: The id of the universe sessions need to be a part of. (string, optional)
  • hostName: The name of the user currently hosting the session. (string, optional)
  • hostId: The id of the user currently hosting the session. (string, optional)
  • minActiveUsers: The minimum amount of active users a session needs to have. (integer, optional, default 0)
  • includeEmptyHeadless: Should empty headless servers be included in the results. (bool, optional, default true)

Users

GET /users/{userId}

Returns the User object for the specified {userId}.

Does not requires authentication, however when authenticated this endpoint will return additional information when {userId} is your own.

URL parameters:

  • byUsername: Interpret the specified {userId} as a username instead. (bool, optional, default false)

GET /users?name={partialUsername}

Returns a JSON array of User objects for the usernames matching the {partialUsername}.

Does not requires authentication.

GET /users/requestlostpassword

Request a password reset email for the specified {emailAddress}.

Does not require authentication.

Body:

{
  "email": "{emailAddress}"
}

GET /users/{userId}/funding/patreon

Get patreon funding information for the specified {userId}.

Requires authentication. {userId} has to be your own.

GET /users/{userId}/exitMessages

Get the exit messages defined by the user with {userId}.

Requires authentication. {userId} has to be your own.

Messages

GET /users/{userId}/messages

Get a list of all messages sent or received by {userId}.


Platform

GET /platform

Provides information about the platform.

Does not require authentication.

{userId} has to be your own.

URL parameters:

  • maxItem: The maximum number of messages to return. Note that if this is not set, every message ever received or sent by {userId} will be returned, which may take some time. (integer, optional)
  • user: Only include messages between {user} and {userId}. (string, optional)
  • unread: Only include unread messages. (bool, optional, default false)
  • fromTime: Only include messages that are after fromTime. This parameter needs to be formatted as an ISO8601 timestring. (string, optional)

Projects working with the API

Instead of relying on spotty API docs, developers may find it easier to use Open Source Software projects utilizing the API as reference instead:

Retrieved from "https://wiki.resonite.com/index.php?title=API&oldid=91033"