Real-Time Update Notifications

The basic character profiles API works well enough for clients that just need to render or edit a roleplay profile once, like websites. However, for the purposes of an in-game plugin, it's insufficient. Other players can edit their character profiles at any time, and it would be nice if the plugin could react to that and immediately fetch and display the updated profile.

For this purpose, Central Archives provides a Socket.io endpoint that allows subscribing to character profile updates. The endpoint address is:

wss://centralarchives.org/updates

Socket.io

The above address is for a Socket.io endpoint, not a raw WebSocket endpoint. Socket.io is an additional layer on top of WebSockets with features like automatic reconnect and fallback to HTTP long polling. The underlying raw WebSocket endpoint is wss://centralarchives.org/socket.io.

Subscription is done via session tokens, which are obtained via the Socket.io endpoint and passed to the character profiles API.

Subscribing to character profile updates

First, connect to the Socket.io endpoint wss://centralarchives.org/updates. The server will send a JSON message, with the event name session:

{
    "sessionToken": "<session token string>"
}

This session token will remain valid for as long as the Socket.io connection persists, and will be invalidated on disconnection.

When retrieving a character profile via the Roleplay API, pass this session token as a query parameter:

https://centralarchives.org/api/rp/v1/characters/profile/<world>/<name>?sessionToken=<session token string>

The client can then cache the retrieved character profile for as long as the Socket.io session persists.

When a character profile that the client is subscribed to is updated, either via the Roleplay API or via the Central Archives website, the Socket.io server sends the following JSON message, with the event name character.updated:

{
    "name": "<character name>",
    "server": "<character world>"
}

This notification is only issued once, after which the client is unsubscribed. When the client receives this message, it should invalidate its local cache for this character profile and re-query it from the Roleplay API with the same session token. This will resubscribe the client to future updates.

If the Socket.io connection closes for any reason (be it a client restart, a server restart, or a network connectivity issue), the client should invalidate its cache for all character profiles already retrieved, re-establish the Socket.io connection, and re-retrieve character profiles with the new session token when the need arises.

From the player's perspective, when the client follows this protocol, it ensures that roleplay profiles displayed in-game (e.g. in mouseover tooltips) are updated in real time when other players make changes.

The Roleplay Profiles plugin is the reference implementation of this kind of caching client.