Skip to main content

​
Overview

The POST /game/new endpoint creates a new Blackjack game for a player. If the player doesn’t exist, they will be automatically created with the provided name.

​
Endpoint

POST /game/new

​
Request Body

​
playerName
string
required
The name of the player. Must not be blank and must be 30 characters or less.

​
Response

Returns a 201 Created status with the following fields:
​
gameId
string
Unique identifier for the newly created game
​
playerId
string
Unique identifier for the player
​
status
string
Current game status. Possible values:
  • IN_PROGRESS - Game is active and waiting for player moves
  • PLAYER_WINS - Player has a natural blackjack and dealer doesn’t
  • DEALER_WINS - Dealer has a natural blackjack and player doesn’t
  • PUSH - Both player and dealer have natural blackjacks

​
How It Works

The CreateNewGameUseCase handles the game creation logic:
  1. Player validation: The player name is validated (must not be blank, max 30 characters)
  2. Player lookup/creation: The system searches for an existing player with that name. If not found, a new player is created
  3. Game initialization: A new game is created with:
    • A shuffled standard 52-card deck
    • Two cards dealt to the player
    • Two cards dealt to the dealer
  4. Natural blackjack check: The game immediately checks if either player or dealer has a natural blackjack (21 with two cards) and sets the status accordingly

​
Example Request

curl -X POST http://localhost:8080/game/new \
  -H "Content-Type: application/json" \
  -d '{
    "playerName": "Alice"
  }'

​
Example Response

{
  "gameId": "550e8400-e29b-41d4-a716-446655440000",
  "playerId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "IN_PROGRESS"
}

​
Error Responses

​
400 Bad Request

Returned when validation fails: 
{
  "timestamp": "2026-03-06T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Player name must not be blank"
}
Common validation errors:
  • Player name is blank or missing
  • Player name exceeds 30 characters

​
Implementation Details

The game creation process (from CreateNewGameUseCase.java:22-40): 
public Mono<CreateGameResult> execute(CreateGameCommand cmd) {
    final PlayerName name;
    try {
        name = new PlayerName(cmd.playerName());
    } catch (IllegalArgumentException e) {
        return Mono.error(new InvalidPlayerNameException(e.getMessage()));
    }

    return playerRepo.findOrCreateByName(name)
            .flatMap(player -> {
                Game game = Game.newGame(player.id());
                return gameRepo.save(game)
                        .map(saved -> new CreateGameResult(
                                saved.id().value(),
                                player.id().value(),
                                saved.status().name()
                        ));
            });
}

​
Next Steps

After creating a game:

Build docs developers (and LLMs) love

Get started for freeTalk to us