Skip to content

Server API and Storage

André Borchert edited this page Aug 22, 2026 · 5 revisions

Server API and Storage

roomcad/server/server.py is the whole backend: Python standard library only, SQLite for storage, reverse-proxied by Caddy under /api/* and bound to 127.0.0.1:8078 so it is never exposed directly.

Authentication

One shared password, checked server-side, supplied through the ROOMCAD_PASSWORD environment variable (never in git). POST /api/login sets an HttpOnly cookie; every other endpoint returns 401 without it. If the password is not configured the service still starts, but logins fail closed.

# log in and keep the cookie
curl -s -c jar.txt -X POST localhost:8078/api/login \
  -H 'Content-Type: application/json' -d '{"password":"letmein"}'
# {"ok": true}

# every later call reuses it
curl -s -b jar.txt localhost:8078/api/rooms

Only a SHA-256 hash of the session token is stored, never the token.

Endpoints

Method Path Purpose
POST /api/login exchange the password for a session cookie
GET /api/rooms list rooms (latest version of each)
GET /api/load/<name> load the latest version, or ?version=N
GET /api/versions/<name> list a room's versions, newest first
POST /api/save save a new version → {name, version}
DELETE /api/rooms/<name> delete every version of a room
GET /api/watch/<name> Server-Sent Events stream of updates
POST /api/live/<name> publish an unsaved live draft
GET /api/session/last the design this browser should reopen
POST /api/session/last remember a design for this browser
GET /api/status {"count": N} — sessions active in the last 30 s

Names are sanitised to [A-Za-z0-9_-]. Saving with an empty name allocates the next free ternak_roomN inside the same lock as the insert, so two simultaneous saves can never collide.

Examples

# save a design (empty name = allocate a new slot)
curl -s -b jar.txt -X POST localhost:8078/api/save \
  -H 'Content-Type: application/json' \
  -d '{"name":"","json":"{\"format\":\"com.maria.roomcad-v2.room\",...}","clientId":"cli"}'
# {"name": "ternak_room4", "version": 1}

# list the versions of that room
curl -s -b jar.txt localhost:8078/api/versions/ternak_room4
# [{"version": 1, "savedAt": 1755900000000}]

# fetch one exact version
curl -s -b jar.txt 'localhost:8078/api/load/ternak_room4?version=1'

# follow live updates (stays open, one JSON object per event)
curl -sN -b jar.txt localhost:8078/api/watch/ternak_room4

Storage

CREATE TABLE rooms (
    id        INTEGER PRIMARY KEY AUTOINCREMENT,
    name      TEXT    NOT NULL,
    version   INTEGER NOT NULL,
    json      TEXT    NOT NULL,
    saved_at  INTEGER NOT NULL,   -- epoch ms
    client_id TEXT,
    UNIQUE(name, version)
);

CREATE TABLE browser_sessions (
    token_hash        TEXT PRIMARY KEY,   -- sha256 of the cookie value
    last_room_name    TEXT,
    last_room_version INTEGER,
    created_at        INTEGER NOT NULL,
    expires_at        INTEGER NOT NULL
);
  • WAL mode, synchronous=NORMAL, busy_timeout=5000 — concurrent readers never block the writer, and a busy save retries instead of failing.
  • One connection is shared across request threads (check_same_thread=False) and every statement is serialised behind a single lock.
  • On first boot, legacy .rcad files in rooms/ are imported as version 1 and removed.

Versioning

POST /api/save always inserts version = max(version) + 1. Nothing is ever overwritten, so any earlier state can be reopened from the version list.

Which design does a browser see?

GET /api/session/last answers it:

  1. If this browser has a remembered room and that exact version still exists → return it.
  2. Otherwise → return the project's most recently saved design, and remember it for this browser (flagged projectLatest: true).
  3. If the project has no saved rooms at all → null, and the app opens the built-in demo.

This lives in SQLite rather than local storage, so it survives an API restart and needs no second cookie.

Live drafts

POST /api/live/<name> keeps the newest unsaved draft per room in memory only and pushes it to every watcher with "live": true. A real save clears it. They are lost on restart, which is fine — they are drafts. See Live Collaboration.

Clone this wiki locally