API and caching

How the API is organised, what every request goes through, how its Redis read cache works and how new data invalidates it, and the rate limits and time limits it applies.

Platform / How the platform works

The API (apps/api) answers every read and write the panel makes, signs people in, serves this handbook and the developer API that game servers call. It is a NestJS app in TypeScript, two copies in production, reachable only through the panel's proxy. Every request goes through the same guards in the same order, and most reads are answered from a Redis cache that new data invalidates within about 30 seconds.

How the API is organised

Each feature is a module under apps/api/src/modules/, hexagonal like the worker's: its rules (domain), its use cases and the ports they need (application), adapters to Postgres, Redis or outside services (infrastructure), and its HTTP routes (presentation). What every module shares is under apps/api/src/shared/. A linter fails the build when an import crosses the layers the wrong way.

  • apps/api/src/
    • modules/one folder per feature
      • games/market reads: games, history, genres, the market overview
      • auth/sign-in, sessions, the session guard, membership checks
      • assistant/the front door to the assistant app
      • developer/game API keys, feedback, the developer API's reads
      • handbook/this handbook: list, page, search
      • notifications/the inbox, preferences, push devices
      • system/the collector status and admin pages
    • shared/
      • cache/the read cache, its policies and interceptor
      • http/validation pipe, error contract, request ids
      • database/the read and write pools
      • redis/the fail-fast Redis client

The other modules are contracts, creators, credentials, dashboard, discovery, github, home, player-hours, portfolio, radar, studio-site and watchlist. Every request and answer shape is a schema in packages/contracts, checked on both sides.

What every request goes through

One request through the API. The panel forwards the request with your session. The session guard refuses cross-site changes, resolves your session and role, and refuses owner-only routes to members. The rate-limit guard counts the request per person and per address. The validation pipe checks the path, query and body against their schemas. The read cache answers a cached read from Redis, otherwise the use case reads Postgres and the answer is stored for the next request.
  1. The session guard

    Refuses (403) a change marked cross-site or from another origin, resolves the session from its token hash (Redis, else Postgres), refuses (403) a change without the x-requested-with: scrywave header, and refuses members on an owner-only route, all before any body is read. See Authentication and permissions.

  2. The rate-limit guard

    Counts the request against your limits per person and per address (below).

  3. Validation

    Every path parameter, query and body goes through one pipe with a schema from @repo/contracts. A body with a field the schema does not name is refused; ids in paths are plain decimal digits; pages and ranges are fixed lists.

  4. The read cache

    A cached GET is answered from Redis when nothing has changed since it was last read; otherwise the use case reads Postgres and the answer is stored.

  5. The answer

    JSON, with X-Request-Id, security headers, and Cache-Control: no-store on every private route so no browser or proxy keeps it.

The read cache: how repeated reads are answered from Redis

A GET route opts in with @CacheRead(policy), and a global interceptor applies it. The answer is stored as the JSON the route would have sent, under a key made of the route, a hash of the path, of the query as the route reads it (defaults filled in, parameters it ignores left out), of the person when the policy is personal, and the current data versions of the domains it reads.

market

/v1/market*, /v1/games, a game, its history and sort ranks, /v1/genres, /v1/rolimons, /v1/radar, /v1/sorts*, /v1/creators/*. Fresh 60 s, then served stale once for up to 300 s while one refresh runs. Shared by everyone.

github

Every GET /v1/github/*. Fresh 120 s, stale up to 600 s. Shared, except Members and a member's page, which are per person because owners see two-factor status.

studio

/v1/studio/*, the studio games on Discovery and a game's hours of the week. Reads the studio and market versions. Fresh 60 s, stale up to 300 s; a game's hub, its bans, a project's detail and your points are per person.

developerMarket

The developer API's market reads, keyed by path and query, never by key, after the key is checked on every request. Fresh 60 s, stale up to 300 s.

site

The public website's /public/site. Fresh 60 s.

How new data invalidates the cache (data versions)

Freshness is a counter, not a clock. Each domain, market, github and studio, has a version in Redis (data:v:<domain>). A bump changes every key that holds that domain's version, so the next read goes to Postgres; old entries are never hunted down and simply expire.

New data reaching the panel. A worker job stores new rows in Postgres and bumps its domain's data version in Redis, at most once every 30 seconds per domain. The next panel read builds a key with the new version, misses the cache, reads Postgres and stores the fresh answer. So new collected data shows in the panel within about 30 seconds.
market bumped by

The worker, after a snapshot batch, metrics recompute, sort reading, recommendations, creators, icons or Rolimon's run that handled anything.

github bumped by

The worker, after every GitHub collection run, successful or not.

studio bumped by

The worker after owned analytics stored rows or a game was released; the API after a game server's feedback is stored.

all bumped by

The API, after any successful change (POST, PUT, PATCH, DELETE) outside sign-in, your own settings, notifications, the assistant and the developer API.

The worker bumps one domain at most once every 30 seconds (DATA_VERSION_INTERVAL_MS), with one trailing bump for changes inside the window, so snapshot batches every few seconds do not empty the cache all the time. A bump never fails a job; if Redis is away, entries expire on their own clock.

Many readers of one key at once

Requests for a key that arrive while it is being read wait for that read and share its answer, never its failure: if the read fails, each waiter reads for itself, uncached. This is also why a cost charged per person, such as looking up an untracked game on Roblox, is charged in a guard before the cache.

Cache headers: X-Cache and ETag

X-Cache

hit, stale (served once while one refresh runs), miss, shared (joined a read under way) or bypass (Redis not in use).

ETag

A strong validator of the body on cached routes. Send it back as If-None-Match and an unchanged answer is 304 with no body.

X-Request-Id

The request's id, also in every error body and log line, so a failure the panel shows can be found in the logs.

GET /v1/collector reports the cache's hits, stale answers, misses, shared reads, errors and hit rate.

When Redis is not there

Without Redis, or with API_CACHE=off, every read goes to Postgres; identical reads arriving together still share one query. With Redis configured but down, commands fail at once, the read goes to Postgres, and the cache leaves Redis alone for five seconds. Rate limits then count per process, and requests go through rather than fail.

API rate limits

WhatLimit per person, per minuteSetting
Reads600API_RATE_LIMIT_READ
Writes120API_RATE_LIMIT_WRITE
Searches, exports, assistant questions60API_RATE_LIMIT_EXPENSIVE
Calls that reach Roblox or GitHub20API_RATE_LIMIT_EXTERNAL

Each client address may make twice a person's limit. Counts are kept in Redis in one-minute windows shared by both copies. A game's servers, with its API key, get 120 requests a minute per key and 1,200 for every key together. Sign-in has its own limits per address: 20 starts and returns, 30 account changes and 600 reads a minute.

Size and time limits

BodyKiB

256, JSON only (API_BODY_LIMIT_BYTES); larger is 413.

AddressKiB

2, query included; longer is 414.

Request timeseconds

20 by default (30 to 60 on a few slow routes); past it, 503 timeout.

Statement timeseconds

8 on reads, 15 on everything else, set on each database connection.

Connections

8 for reads and 4 for writes, per copy.

Errors: one shape for every refusal

Every refusal has one body, { "error": { "code", "message", "requestId", "issues"? } }. code is stable for code, message is a sentence for a person, issues names fields. No answer carries a stack trace, SQL, a table name or a value the request sent.

StatuscodeWhen
400validation_failedA parameter, query or body failed its schema
401unauthenticatedNo session that counts
403forbiddenNot an owner or not this record's lead, a cross-site change
404not_foundNot tracked, not yours, or no such route
409conflictAlready exists, or another change got there first
422constraint_violatedA value breaks a rule the database enforces
429rate_limitedOver a rate limit; Retry-After says when
503timeoutThe request or a statement ran past its time
503unavailablePostgres cannot be reached, or the API is stopping
500internalAnything else; the request id finds it in the logs

Conventions every answer follows

Times

ISO 8601 in UTC, such as 2026-09-29T22:51:21.000Z.

Growth

A ratio: 0.5 is +50%.

Unknown

null, never 0. See Empty is never zero.

Ids

Universe ids are numbers; GitHub and public place ids are decimal strings.

Related: Architecture, Authentication and permissions, Data model, The developer API.

Updated