Leaderboards

Reading a leaderboard's settings and scores, and submitting scores. Every score belongs to a player: a game submits for whoever is signed in, and your own server, with a key holding submit_for, may submit for any player of the game.

Scores and score bounds come back as decimal strings, such as "1250.5", so no precision is lost on the way. Entries by banned or deleted players are left out of every answer, and out of the ranking.

Objects

Shapes that more than one endpoint answers with. Fields marked as the tenant's appear only in answers to your own server's calls.

Score

Score {
  id: string,
  player: string,               // the player's public id
  player_name: string,          // the name shown beside the entry
  score: string,                // a decimal, such as "1250.5"
  secondary_score: string | null,
  added: string,                // ISO datetime
  updated: string,              // ISO datetime
  extra_data: any | null,       // whatever the game stored with it
}

/api/lb/<leaderboard_id>/

GET

Answers:

{
  id: string,
  name: string,
  description: string,
  game: string,                 // the game's id
  ordering: "desc" | "asc",     // "desc" puts the highest score first
  secondary_ordering: "desc" | "asc",
  unique: boolean,              // one entry per player, their best
  min_score: string | null,     // a decimal; scores below it are refused
  max_score: string | null,     // a decimal; scores above it are refused
  entries: int,                 // not counting banned or deleted players
}

/api/lb/<leaderboard_id>/score/

An entry belongs to a player and names them by their public id. The entries of banned and deleted players are left out, and out of the ranking.

GET parameters, all optional:

• limit, offset, page: Pagination. page is 1-based and, when given, overrides offset.
• order: best (default), worst, newest or oldest.
• since, until: ISO date or datetime bounds on when the score was set. These scope the board itself, so rank is counted among the scores inside them.
• player_name, min_score, max_score: Narrow which entries come back without changing their rank.
• player: A player's id. Only that player's entries, each with its rank.
• around: A player's id. Returns the limit entries centred on that player's best entry, and that entry's rank and id as player_rank and player_score.

GET

Answers:

{
  leaderboard: string,          // the leaderboard's id
  count: int,                   // entries that match, on every page
  offset: int,
  limit: int,
  next_offset: int | null,      // null on the last page
  scores: [Score & { rank: int }],
  // Only with around:
  player_rank: int,             // the rank of that player's best entry
  player_score: string,         // that entry's id
}

POST

Submit a score for the signed-in player. On a unique board that updates their entry, but only if the new score beats it. Either way the response is the player's best entry.

A key holding submit_for may name any of the game's players in player instead, which is how a tenant's own server submits.

player_name is the name to show beside the entry. Left out, the player's display name is used.

Answers 201 when the call made a new entry, 200 when it did not:

Score & {
  rank: int,
  improved: boolean,            // whether this submission is now their best
  submitted: string | null,     // the id of the entry this call made, if any
}

/api/score/<score_id>/

GET

Answers a Score.

DELETE

Answers:

{ deleted: string }             // the score's id