Basics
JSON over HTTP under /api/v1. Errors are {"error": "code", "message": "text"} with a 4xx/5xx status.
Players are recognised by their device signature (a hash of the device's id, made by the game): signing in with it gives a session token, sent as Authorization: Bearer <token>. To a game server they identify with a play session id, which is tied to that device and so to the account.
Game servers register with the shared secret in X-Server-Key, then use their own token as Authorization: Bearer <server token>.
Game servers (/server-api/)
| Call | Who | What |
|---|---|---|
POST /server-api/v1/sign-up | X-Server-Key | "Hello, I want to sign up" (on start): {name, port, version, kind: host|standalone, modes[], max_players, address?} (address defaults to where the request came from) → {server_id, token, heartbeat_secs} |
POST /server-api/v1/heartbeat | server token | Still alive: {players, modes?}, about every 30 s. Silent for 90 s = off the list. |
POST /server-api/v1/sign-off | server token | "I'm turning off" (on shutdown): off the list right away. Signing up again brings it back. |
POST /server-api/v1/matches/start | server token | A game started, or its players changed: {match, mode, map, port, players: [{name, hero, bot, team, session}]}. It is in the players' history right away (unfinished) and the game can take a player back to it. {match, abandoned: true} calls it off |
POST /server-api/v1/matches | server token | A finished game: {mode, map, winner_team?, started_at?, players: [{session?, name, hero, bot, team, place, gems, goals, laps}]}. session is the play session the player joined with; their account gets trophies, coins and quest progress → {match_id, results} |
Players
| Call | Who | What |
|---|---|---|
GET /api/v1/servers?version=0.2.0 | anyone | Servers online (the game asks this for its server list) (same major.minor as version) → {servers: [{name, address, port, kind, modes, players, max_players, version, last_seen}]} |
POST /api/v1/sessions/device | anyone | Sign in by the device's recognition id {device, vlastnosti: {version, hash}, name?, os?}: the account this device belongs to, or a new guest account the first time → {token, account, new}. The game values must be the live ones (version and SHA-256 of the file, line endings ignored), else 409 vlastnosti_outdated. A token sent in Authorization is kept if it is this account's |
POST /api/v1/me/play-session | player | A play session {device, vlastnosti} (live game values needed, as for signing in) → {session, expires_at}: what the game gives a game server to say who it is. Tied to the device (and its account), can't sign in, runs out after 12 h |
GET /api/v1/vlastnosti | anyone | The live game values → {version, hash, content} (content: the vlastnosti.json text) |
GET /api/v1/me | player | Your account: name, coins, gems, trophies, heroes, Jlude link, activity |
PATCH /api/v1/me | player | Rename {name} (1-16 characters) |
POST /api/v1/me/activity | player | What you're doing {status: menu|searching|in_game|offline, mode?, server?} |
POST /api/v1/me/jlude | player | Link to Jlude {jlude_token} |
POST /api/v1/sessions/jlude | anyone | Sign in on a new device with a linked Jlude account {jlude_token, device?} → {token, account} |
POST /api/v1/me/logout | player | This token stops working |
GET /api/v1/heroes | anyone | Heroes and their prices |
POST /api/v1/me/heroes/:id/unlock | player | Buy a hero with coins |
GET /api/v1/me/quests | player | Your open quests (always 3) with progress |
POST /api/v1/me/quests/:id/claim | player | Take a finished quest's reward; a new quest replaces it |
GET /api/v1/me/matches?limit=20 | player | Your match history, newest first; each game has status running / finished / unfinished, and a running one its address and port |
GET /api/v1/players/:id/matches?limit=20 | anyone | Another player's match history (without addresses) |
GET /api/v1/me/recent-players | player | People you played with lately (accounts only, online first) with their trophies, favourite hero and activity: the squad list |
GET /api/v1/players/:id | anyone | Someone's public profile (no coins/gems) |
GET /api/v1/stats | anyone | Right now: players online (and how many are in a game, looking for one, in the menu), servers online, players on servers |
GET /api/v1/leaderboard | anyone | Top players by trophies |
GET /api/v1/matches/recent | anyone | Latest games on all servers |