Terminal API¶
The player terminal talks to NestrisLTM only through this REST API. The base path is /api/terminal/v1. Every request carries a bearer token with the terminal scope. The token lives in the terminal's local bridge and never reaches the browser UI.
Endpoints¶
| Method | Path | Purpose |
|---|---|---|
GET |
/ping |
Reachability and server version |
GET |
/card/{uid}?name= |
Who owns this card? Returns known, name_match or unknown |
POST |
/card/{uid}/link |
Link a card UID to an existing player |
GET |
/nickname?value= |
Is this nickname still free? |
POST |
/players |
Register a new player (with e-mail consent) |
GET |
/players/{id} |
Player profile: stats, events, games |
POST |
/players/{id}/games |
Self-reported score (flagged self_reported) |
GET |
/highscore |
Leaderboard of the active event |
GET |
/games/{id}/recording |
NGF recording for the replay viewer |
Card lookup logic¶
flowchart TD
A["<span style='color:#111111'>Card placed<br/>uid + name from reader</span>"]:::rfid --> B{"<span style='color:#111111'>GET /card/{uid}</span>"}:::ltm
B -- known --> P["<span style='color:#111111'>Open player page</span>"]:::term
B -- name_match --> L["<span style='color:#111111'>POST /card/{uid}/link<br/>(older card, known name)</span>"]:::ltm --> P
B -- unknown --> R["<span style='color:#111111'>Registration with<br/>this card attached</span>"]:::term
classDef ltm fill:#f5b800,stroke:#7a5c00,color:#111,stroke-width:2px
classDef term fill:#a78bfa,stroke:#6d28d9,color:#111,stroke-width:2px
classDef rfid fill:#f472b6,stroke:#be185d,color:#111,stroke-width:2px
Design notes¶
- No direct database access. The terminal can be replaced, restarted or run on any PC in the LAN without touching the database.
- Versioned path. The
v1in the path lets the contract evolve without breaking terminals that are already deployed. - Least privilege. A
terminaltoken can register players, link cards, add self-reported scores and read public data. It cannot change existing games or any settings. - Privacy. Only nicknames are returned in public lists. An e-mail address is stored only with the player's consent.