Realtime

Manages WebSocket connections to the platform

Experimental feature: this API is likely to change.

Service health check

GEThttps://your-organization-id.m2worlds.io/api/realtime/healthz/

Response

200

Provides information about the service status.

Body

application/json

statusMessage (string)

Provides information about the service status.

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/realtime/healthz/', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

text

Connect to the realtime service

Creates a websocket connection to the realtime service, sending messages to the realtime service will subscribe you to different resources allowing you to listen to document updates in realtime. When subscribing if a resource doesn't exist yet a listener will be created and will be triggered when the resource is created. If the resource is deleted the listener will still exist so make sure to unsubscribe when you no longer need the resource.

When connecting via a html websocket you will need to parse all of your headers in through Sec-WebSocket-Protocol which is an optional header that takes in a string. Format for the string needs to be a list of headers split by \n and key value split by : and then encoded into base58

Example format

x-m2-organization:testOrg x-m2-project:testProj

Example messages for subscribing to the resources available in the realtime service -

• KVStore:

    {
        "action": "subscribe",
        "resource": {
            "type": "kvStore",
            "id": "World:kvstoreClient:testKey"
        }
    }
  

• Collections:

    {
        "action": "subscribe",
        "resource": {
            "type": "collection",
            "id": "public"
        }
    }
  

• Liveconfig:

    {
        "action": "subscribe",
        "resource": {
            "type": “liveConfig",
            "id": “game"
        }
    }
  

Using the same format, you can also unsubscribe from the resources by changing the action to "unsubscribe" and sending the same resource.

Example response formats below.

Success:

    {
      "userId": "fakeUserId",
      "resource": {
          "type": "collection",
          "id": "private"
      },
      "data": {
          "userId": "fakeUserId",
          "datasourceId": "fakeDatasourceId",
          "userCollection": []
      },
      "version": "2024-01-30T15:50:35.742Z"
    }

Warning:

    {
      "warning": "resource_not_found",
      "message": "KVStore resource doesn't currently exist, subscription was still made successfully"
    }

Error:

    {
      "error": "Invalid message format"
    }

GEThttps://your-organization-id.m2worlds.io/api/realtime/connect/

Authorization

BearerAuth

Header parameters

Response

1014XX

Default Response

Body

application/json

any of

statusMessage (string)realtimeWarningResponse (object)realtimeErrorResponse (object)

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/realtime/connect/', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>",
      "x-m2-organization-id": "text"
    },
});
const data = await response.json();

Response

1014XX

text