The API

We assume ChessHop already uses a RESTful HTTP API, and we give the leaderboard one too. The requirements ask for three things: a page of the leaderboard, a player’s rank with the players around it, and a player’s rank on their profile.

A page of the leaderboard

A page holds 50 players. Page 1 is ranks 1 to 50, page 2 is ranks 51 to 100, and page 3 is ranks 101 to 150.

Request:

GET /leaderboards/blitz?page=3

Response:

{
  "timeControl": "blitz",
  "page": 3,
  "players": [
    { "rank": 101, "playerId": 5512, "username": "knightowl", "rating": 2140 },
    { "rank": 102, "playerId": 90311, "username": "pawnstorm", "rating": 2140 }
  ]
}

The real response holds 50 players. Two are shown here. Players 5512 and 90311 have the same rating. Player 5512 reached 2140 first, so player 5512 is ranked higher.

The time control is part of the path, because each time control has its own leaderboard. The page is a query parameter. The Public Courses API also takes the page as a query parameter. The page size is always 50, so it has no parameter.

A player’s rank

Request:

GET /leaderboards/blitz/players/5512

The response holds player 5512’s rank, 101, and the players around it: 5 players above and 5 below. This is what a player sees when they jump to their own rank.

A profile shows the player’s rank in each time control. So the profile page sends this request once for each of the three time controls.

No endpoint for setting a rating

Both endpoints are reads. Should there be a POST or a PUT to set a player’s rating?

Let’s think about who would send that request. A client should not, because a client could send any rating it likes. The new ratings come from the game service. The game service computes them when a game ends. How the game service gets them to the leaderboard is a separate design question.

Public responses

Neither endpoint needs the client to sign in. Two clients that send the same request get the same response.