Leaderboards ~ API concept

This page outlines ideas and resources for implementing a Leaderboard API in ChiGame.

Conceptual Overview

The Leaderboard API will record and retrieve player rankings across games. At a minimum, it is expected to support:

• Per-Game Leaderboards: Each game defines how points are earned and has a leaderboard showing top players. Boards may include a best single-game score and an aggregate score across all sessions.

• Global Leaderboards: An all-games leaderboard, aggregating and ranking players across the platform. Score normalization will be needed (to avoid users from point-farming with a game that awards a large amount of points).

• Filtered Views: Support for region-based or friend-group leaderboards to compare within smaller communities.

• Achievement/Session Rankings: Boards may also rank players by badges, milestones, or performance in individual matches.

External resources

• Django REST Framework: Since ChiGame is built with Django, DRF would be the go-to library for creating the Leaderboard API endpoints. DRF provides tools for serializing data (scores, user info) and handling requests, making it easier to expose leaderboard data in JSON. It also integrates well with Django’s ORM, so we can tie into existing models (Game, User, Match) to gather or update score data.

• Redis: An in-memory data store frequently used for leaderboards. Redis’s Sorted Set data structure makes it straightforward to store scores with their ranks and query them in order​ redis.io. Using Redis, the API can quickly update scores and retrieve ranking information in O(log N) time (ideal for high-frequency reads/writes).

• Firebase Realtime Database / Firestore: Can implement real-time leaderboards in games. They handle synchronization and updates to client devices automatically. For example, a game can push score updates to Firebase and use listeners to update leaderboard UIs instantly across all players. This reduces the need to build a lot of real-time infrastructure from scratch.

API workflow concept

• POST /api/games/{game_id}/scores/ – Submit Score: Allows a user to submit a new score for a specific game. The request body includes the score (and implicitly the user, from auth context). The server records the score and updates the leaderboard (either setting a new high score or adding to the user’s cumulative total).

• GET /api/games/{game_id}/leaderboard/ – Game Leaderboard (All-Time): Retrieves the all-time leaderboard for the specified game, ranked by each player's highest single-game score. Returns a ranked list of top players and their scores. Supports optional query parameters (e.g. ?region={region_code} to filter by region, or ?friends=true to show only the current user’s friends).

• GET /api/games/{game_id}/leaderboard/daily/ – Game Leaderboard (Daily): Returns the top players for the current day in the specified game, based on their best score of the day (daily leaderboard resets every 24 hours). The response is a ranked list of today’s high scores. Also supports optional region and friends filters for localized or friends-only results.

• ** GET /api/games/{game_id}/leaderboard/cumulative/** – Game Cumulative Leaderboard (All-Time): Retrieves the all-time leaderboard for the game based on cumulative scoring. Players are ranked by their total accumulated points (sum of all scores) in that game. Returns the top users by total points, with optional region or friends query parameters to filter the results.

• GET /api/games/{game_id}/leaderboard/cumulative/daily/ – Game Cumulative Leaderboard (Daily): Similar to the above, but scoped to the current day. Ranks players by the total points they have earned today in the specified game. This endpoint resets daily and supports the same optional filters (region or friends-only).

• GET /api/leaderboards/global/ – Global Leaderboard (All-Time): Provides a platform-wide all-time leaderboard across all games. Users are ranked by an aggregate score (e.g. total points earned across all ChiGame games). Returns the top players overall. Supports optional filters like region (to restrict by geographic region) or friends=true (to show only the requesting user’s friends on the global scale).

• GET /api/leaderboards/global/daily/ – Global Leaderboard (Daily): Provides a platform-wide daily leaderboard, ranking users by the total points earned across all games for the current day. Returns top users for today across the platform. Optional query parameters region or friends can be applied here as well for region-specific or friends-only daily rankings.

Each of the GET endpoints returns data in JSON, including fields like player identifier, score, and rank.