Upstream/docs/API.md
jvanvik b56b13880e Stage 0-2 server spine: db, scheduler, REST, auth, economy, map
Built: SQLite (node:sqlite) via server/db.js with checksummed migrations, injectable clock, persistent event
scheduler with catch-up, tiny REST router (error envelope, idempotency keys, rate limits, bearer tokens with scrypt
passwords), lazy-resource economy in public/js/rules.js + data.js, build/cancel/rename commands, seeded map +
spawn ring, generated docs/openapi.json. NETWALL net.js/static.js reused.
Tested: manual smoke run only (signup, town view, build, map). No unit tests or e2e yet.
NOT done: military, expansion, social, client, push, deploy docs, bots/admin.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
2026-10-11 18:07:42 +02:00

1.9 KiB

API

REST JSON under /api/v1/. The machine-readable contract is docs/openapi.json, generated from the route table (npm run openapi); this file covers conventions and per-resource notes.

Conventions

  • Auth: Authorization: Bearer <token> (opaque, one per device; POST /auth/login or /auth/signup issues one, POST /auth/logout and DELETE /auth/tokens/:id revoke). No cookies.
  • Every response is an object with serverTime (integer ms since epoch, server clock). Clients compute countdowns from the offset.
  • Errors: { serverTime, error: { code, message, details } }. Clients switch on code. All codes: x-error-codes in openapi.json.
  • Mutating POSTs accept Idempotency-Key (8-64 chars A-Za-z0-9_.:-); a replay returns the stored response with Idempotent-Replay: true; the same key with a different request is idempotency_key_reuse.
  • Lists are cursor-paginated: ?after=<id>&limit=<n>, response next is the cursor or null.
  • Rate limits: per IP, per token, stricter on login/signup. 429 rate_limited with Retry-After.
  • The client never sends computed amounts, only intents. The server recomputes everything with public/js/rules.js.

Resources (stage 0-2)

Route Purpose
POST /auth/signup, POST /auth/login account + token (signup also founds the capital POP)
GET /me user, operators (per world), POPs
GET /towns/:id full POP state: resources {amount, rate, cap} at serverTime, power, buildings with the server's build plan, queue
POST /towns/:id/build {key} build/upgrade one level of a field (f1..f18) or an infrastructure building
DELETE /towns/:id/queue/:eventId cancel a running build, 80% refund
GET /map?x&y&r rural areas, incumbent sites, POPs in the viewport
GET /notifications?after&limit durable notification feed (build done, ...)

Later stages append their routes here and to the route table.