Skip to content

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.

GET /api/terminal/v1/ping HTTP/1.1
Host: 192.168.50.10:7990
Authorization: Bearer nltm_…

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 v1 in the path lets the contract evolve without breaking terminals that are already deployed.
  • Least privilege. A terminal token 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.