Skip to main content

​
Overview

The GET /game/{id} endpoint retrieves the current state of a Blackjack game, including player and dealer hands, scores, and game status.

​
Endpoint

GET /game/{id}

​
Path Parameters

​
id
string
required
The unique identifier of the game

​
Response

Returns a 200 OK status with the following fields:
​
gameId
string
The unique identifier for the game
​
playerId
string
The unique identifier for the player
​
status
string
Current game status. Possible values:
  • IN_PROGRESS - Game is active
  • PLAYER_BUST - Player exceeded 21
  • DEALER_BUST - Dealer exceeded 21
  • PLAYER_WINS - Player won the game
  • DEALER_WINS - Dealer won the game
  • PUSH - Game ended in a tie
​
playerScore
integer
The current score of the player’s hand (0-21 or higher if bust)
​
dealerScore
integer
The dealer’s score. Important: If the game is still IN_PROGRESS, this only shows the value of the dealer’s visible card, not their full hand score.
​
playerCards
array
Array of card objects in the player’s hand. Each card has:
  • rank (string): Card rank (e.g., “ACE”, “KING”, “SEVEN”)
  • suit (string): Card suit (“HEARTS”, “DIAMONDS”, “CLUBS”, “SPADES”)
  • hidden (boolean): Always false for player cards
​
dealerCards
array
Array of card objects in the dealer’s hand. Important: While the game is IN_PROGRESS, only the first card is visible. Hidden cards have null rank and suit with hidden: true.

​
Card Visibility Rules

The API implements standard Blackjack card visibility rules:

​
During Active Game (status = IN_PROGRESS)

  • Player cards: All cards are visible
  • Dealer cards: Only the first card is visible, remaining cards are hidden
  • Dealer score: Only shows the value of the first visible card

​
After Game Ends (any final status)

  • Player cards: All cards visible
  • Dealer cards: All cards visible
  • Dealer score: Shows the full hand score
This is implemented in GameStateMapper.java:15-34, where the dealer’s cards and score are conditionally hidden based on game status.

​
Example Requests

curl -X GET http://localhost:8080/game/550e8400-e29b-41d4-a716-446655440000

​
Example Responses

​
Game In Progress

{
  "gameId": "550e8400-e29b-41d4-a716-446655440000",
  "playerId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "IN_PROGRESS",
  "playerScore": 18,
  "dealerScore": 10,
  "playerCards": [
    {
      "rank": "JACK",
      "suit": "HEARTS",
      "hidden": false
    },
    {
      "rank": "EIGHT",
      "suit": "DIAMONDS",
      "hidden": false
    }
  ],
  "dealerCards": [
    {
      "rank": "TEN",
      "suit": "CLUBS",
      "hidden": false
    },
    {
      "rank": null,
      "suit": null,
      "hidden": true
    }
  ]
}
Notice that:
  • The dealer’s second card is hidden (rank and suit are null, hidden is true)
  • The dealerScore only reflects the visible card (10)

​
Game Finished (Player Wins)

{
  "gameId": "550e8400-e29b-41d4-a716-446655440000",
  "playerId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "PLAYER_WINS",
  "playerScore": 20,
  "dealerScore": 19,
  "playerCards": [
    {
      "rank": "JACK",
      "suit": "HEARTS",
      "hidden": false
    },
    {
      "rank": "EIGHT",
      "suit": "DIAMONDS",
      "hidden": false
    },
    {
      "rank": "TWO",
      "suit": "SPADES",
      "hidden": false
    }
  ],
  "dealerCards": [
    {
      "rank": "TEN",
      "suit": "CLUBS",
      "hidden": false
    },
    {
      "rank": "NINE",
      "suit": "HEARTS",
      "hidden": false
    }
  ]
}
Notice that:
  • All dealer cards are now visible
  • The dealerScore shows the complete hand value (19)
  • The status indicates the final outcome

​
Game Finished (Push/Tie)

{
  "gameId": "550e8400-e29b-41d4-a716-446655440000",
  "playerId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "PUSH",
  "playerScore": 19,
  "dealerScore": 19,
  "playerCards": [
    {
      "rank": "KING",
      "suit": "DIAMONDS",
      "hidden": false
    },
    {
      "rank": "NINE",
      "suit": "CLUBS",
      "hidden": false
    }
  ],
  "dealerCards": [
    {
      "rank": "ACE",
      "suit": "HEARTS",
      "hidden": false
    },
    {
      "rank": "EIGHT",
      "suit": "SPADES",
      "hidden": false
    }
  ]
}

​
Error Responses

​
404 Not Found

Returned when the game doesn’t exist: 
{
  "timestamp": "2026-03-06T10:30:00Z",
  "status": 404,
  "error": "Not Found",
  "message": "Game not found: 550e8400-e29b-41d4-a716-446655440000"
}

​
Implementation Details

The GetGameStateUseCase retrieves the game and maps it to the response format (GetGameStateUseCase.java:20-24): 
public Mono<GameStateResult> execute(String gameId) {
    return gameRepo.findById(new GameId(gameId))
            .switchIfEmpty(Mono.error(new GameNotFoundException(gameId)))
            .map(mapper::toResultForPlayer);
}
The GameStateMapper handles the card visibility logic, ensuring dealer cards are properly hidden during active gameplay.

​
Response Schema

{
  "gameId": "string",
  "playerId": "string",
  "status": "IN_PROGRESS | PLAYER_BUST | DEALER_BUST | PLAYER_WINS | DEALER_WINS | PUSH",
  "playerScore": "integer",
  "dealerScore": "integer",
  "playerCards": [
    {
      "rank": "string | null",
      "suit": "string | null",
      "hidden": "boolean"
    }
  ],
  "dealerCards": [
    {
      "rank": "string | null",
      "suit": "string | null",
      "hidden": "boolean"
    }
  ]
}

​
Use Cases

  • Check the current state before making your next move
  • Display the game to the player in a UI
  • Verify the outcome after the game has ended
  • See which cards have been dealt
  • Monitor your score and the dealer’s visible card

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us