Skip to main content

MagicWeave SDK: Realtime Database

This guide documents the Firebase RTDB-style realtime tree API exposed for game clients.

The client_realtime module lets you:

  • read any JSON tree node/subtree by path
  • set or merge JSON values at a path
  • delete a path and all its descendants
  • subscribe to realtime updates over WebSocket

All data is project scoped based on your client credentials and player auth.

Base URL and Route Prefix​

Base URL:

  • https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/

Realtime routes are under:

  • /realtime

Examples:

  • GET https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/realtime/db/users/alice

Required Headers (REST + WS handshake)​

All REST endpoints and the WebSocket handshake require:

  • x-client-id: <project_client_id>
  • x-client-secret: <project_client_secret>
  • Authorization: Bearer <access_token>
  • Content-Type: application/json (for PUT and PATCH request bodies)

The authenticated user must have the appropriate realtime DB permission (for example client.realtime).

Data Model Semantics​

  • Paths are normalized internally (no leading/trailing slash).
  • PUT /db/{path} behaves like Firebase set: if value is an object, it replaces the subtree under that path.
  • PATCH /db/{path} merges object keys by applying child updates to the existing value.
  • DELETE /db/{path} removes the path and all descendants.

The server stores arbitrary JSON at each path.

REST Endpoints​

Endpoint 1: Read any node/subtree​

GET /realtime/db/{path}

Response:

{
  "path": "users/alice",
  "value": {
    "name": "Alice",
    "status": "online"
  }
}

Behavior:

  • Returns the current JSON value at the requested path.
  • If the path does not exist, the server may return "value": null or 404 depending on implementation.

Reference: Get realtime DB node/subtree

Endpoint 2: Set/overwrite node​

PUT /realtime/db/{path}

Request:

{
  "value": {
    "name": "Alice",
    "status": "online"
  }
}

Behavior:

  • Completely replaces the value at the path.
  • When value is an object, the entire subtree under that path is replaced.

Reference: Set/overwrite realtime DB node

Endpoint 3: Merge update node​

PATCH /realtime/db/{path}

Request:

{
  "value": {
    "status": "offline"
  }
}

Behavior:

  • Merges the object in value into the existing JSON at the path.
  • Only specified keys are updated; other keys remain unchanged.

Reference: Merge update realtime DB node

Endpoint 4: Delete node/subtree​

DELETE /realtime/db/{path}

Response:

{
  "deleted": "users/alice"
}

Behavior:

  • Deletes the path and all children below it.

Reference: Delete realtime DB node/subtree

WebSocket Endpoint​

GET /realtime/ws

The WebSocket handshake uses the same auth headers as REST:

  • x-client-id
  • x-client-secret
  • Authorization: Bearer <access_token>

After upgrade, clients and server exchange JSON messages.

Client messages​

Subscribe:

{
  "action": "subscribe",
  "path": "rooms/room1"
}

Unsubscribe:

{
  "action": "unsubscribe",
  "path": "rooms/room1"
}

Set node via WebSocket:

{
  "action": "set",
  "path": "rooms/room1/messages/msg1",
  "value": {
    "text": "Hello",
    "from": "alice"
  }
}

Server messages​

Initial snapshot:

{
  "event": "init",
  "path": "rooms/room1",
  "value": {
    "messages": {
      "msg1": {
        "text": "Hello",
        "from": "alice"
      }
    }
  }
}

Live update:

{
  "event": "update",
  "path": "rooms/room1/messages/msg2/text",
  "value": "Hey there"
}

Behavior:

  • When you first subscribe to a path, the server sends an event: "init" snapshot for that subtree.
  • Subsequent writes under that subtree emit event: "update" messages with the affected path and new value.

Realtime broadcasts are propagated through Redis pub/sub so subscriptions continue to work across multiple API workers/instances.

cURL Examples​

Read node​

curl -X GET "https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/realtime/db/users/alice" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>"

Set node​

curl -X PUT "https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/realtime/db/users/alice" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"value":{"name":"Alice","status":"online"}}'

Patch node​

curl -X PATCH "https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/realtime/db/users/alice" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"value":{"status":"offline"}}'

Delete node​

curl -X DELETE "https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/realtime/db/users/alice" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>"

Integration Notes for Game Teams​

  • Use hierarchical paths for chat rooms, lobbies, and presence, e.g. rooms/{roomId}/messages/{messageId}.
  • Combine a one-time REST read with a WebSocket subscription, or rely on the init event for initial state.
  • Prefer PATCH for small incremental updates to avoid overwriting whole subtrees.
  • Be careful when using PUT on a path that already has children—you will replace the entire subtree.
  • Handle disconnects and reconnects by re-subscribing and reloading state as needed.