Skip to main content

​
Endpoint

Returns the ranking of all players ordered by score (wins minus losses) with tie-breakers applied.

​
Response

Returns an array of ranking entries, each containing:
​
position
int
The player’s rank position (1-based index)
​
playerId
string
Unique identifier (UUID) of the player
​
name
string
The player’s display name
​
wins
int
Number of games won by the player
​
losses
int
Number of games lost by the player
​
score
int
Calculated score (wins - losses) used for ranking

​
Ranking Calculation

Players are ranked based on their score, which is calculated as: 
score = wins - losses
The ranking is determined by:
  1. Primary sort: Score (descending) - higher scores rank first
  2. Tie-breaker: Applied by the repository implementation when scores are equal
Players with the same score may have their relative positions determined by tie-breaking rules implemented at the database level.

​
Example Request

curl -X GET http://localhost:8080/ranking

​
Example Response

Response (200 OK)
[
  {
    "position": 1,
    "playerId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Alice Supreme",
    "wins": 15,
    "losses": 3,
    "score": 12
  },
  {
    "position": 2,
    "playerId": "8d0f7780-8536-51ef-b827-557766551111",
    "name": "Bob the Builder",
    "wins": 10,
    "losses": 5,
    "score": 5
  },
  {
    "position": 3,
    "playerId": "9e1g8891-9647-62fg-c938-668877662222",
    "name": "Charlie",
    "wins": 8,
    "losses": 4,
    "score": 4
  },
  {
    "position": 4,
    "playerId": "af2h9902-0758-73gh-d049-779988773333",
    "name": "Diana",
    "wins": 3,
    "losses": 7,
    "score": -4
  }
]

​
Empty Rankings

If no players have been created yet, the endpoint returns an empty array:
Response (200 OK)
[]

​
Understanding Scores

Positive Score

A player with more wins than losses has a positive score and ranks higher.Example: 10 wins, 3 losses = score of 7

Negative Score

A player with more losses than wins has a negative score and ranks lower.Example: 2 wins, 5 losses = score of -3

Zero Score

A player with equal wins and losses has a score of 0.Example: 5 wins, 5 losses = score of 0

New Players

New players start with 0 wins and 0 losses, giving them a score of 0.Example: 0 wins, 0 losses = score of 0

​
Implementation Details

The ranking endpoint is implemented using reactive programming with Project Reactor: 
public Flux<RankingEntryResult> execute() {
    return playerRepo.findRanking()
            .index()
            .map(tuple -> toEntry(tuple.getT1(), tuple.getT2()));
}

private RankingEntryResult toEntry(long idx, Player p) {
    return new RankingEntryResult(
            (int) idx + 1,  // Position (1-based)
            p.id().value(),
            p.name().value(),
            p.wins(),
            p.losses(),
            p.score()       // Calculated as wins - losses
    );
}
1

Fetch Ranked Players

The repository’s findRanking() method returns players sorted by score (descending):
playerRepo.findRanking()
2

Add Position Index

The .index() operator adds a 0-based index to each player in the stream:
.index()
3

Map to Result

Each player is converted to a RankingEntryResult with position (1-based), player details, and calculated score:
.map(tuple -> toEntry(tuple.getT1(), tuple.getT2()))
4

Return as Flux

The result is returned as a reactive Flux<RankingEntryResult> which Spring WebFlux automatically serializes to JSON:
public Flux<RankingEntryResult> getRanking() {
    return viewRanking.execute();
}

​
Use Cases

The ranking endpoint is useful for:
  • Leaderboards: Display the top players in your application
  • Player Profiles: Show a player’s current rank and compare with others
  • Analytics: Track player performance over time
  • Gamification: Encourage competition by showcasing rankings
Since this endpoint returns all players, consider implementing pagination if you expect a large number of players in production.

Player Overview

Learn about the Player aggregate and statistics

Change Player Name

Update a player’s display name

Build docs developers (and LLMs) love

Get started for freeTalk to us