API docs by Redocly

Dice Game API (1.0.0)

Download OpenAPI specification:

This API describes the Dice Game API for the Full Fabric Frontend code interview.

The game is turn-based, strictly between two players. Players take turns attacking or defending against each-other by rolling dice; any damage dealt is decremented from the defending player's HP, until one of them reaches 0, at which point a winner is declared and the game ends.

The rules are as follows:

  • A game must have two players.
  • Each player starts with the same HP, which defaults to 20.
  • A game is played with a single N-sided die, which defaults to 6 sides.
  • The game starts by selecting the attacker and defender at random.
  • Each turn, each player rolls the die once.
  • The rolls determine the attack and defense values, depending on the player's role that turn.
  • If the attack value is greater than the defense value, the defending player takes damage equal to the difference between the two values.
  • After damage is dealt, and if all players are still alive (HP > 0) their roles are switched.
  • The players continue taking turns attacking and defending until one of them dies and is declared the winner.

Below are the endpoints available to manage games, assign players, and take turns.

List all games

Returns a list of all games in descending order of creation. Includes the game's players in the response.

Responses

Response samples

Content type
application/json
{
  • "games": [
    ]
}

Create a new game

Creates a new game with the default die size and starting HP, if these are not provided. A new Game has no players or turns, so these are not returned.

Request Body schema: application/json
optional
dieSize
integer [ 1 .. 100 ]
startingHP
integer [ 1 .. 100 ]

Responses

Request samples

Content type
application/json
{
  • "dieSize": 6,
  • "startingHP": 20
}

Response samples

Content type
application/json
{
  • "game": {
    }
}

Get game details

Returns the details of a game, including the game's players and turns.

path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "game": {
    }
}

Join an existing game

Joins a game as a player, if the game is not full. This creates a new Player instance for the caller, and returns its ID.

path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
playerName
required
string

The name of the player.

Responses

Request samples

Content type
application/json
{
  • "playerName": "string"
}

Response samples

Content type
application/json
{
  • "game": {
    },
  • "playerId": "35184259-d156-4290-94ed-3a4b4f2c36f8"
}

Start a game

Starts a game, selecting the attacker and defender at random. The game will have a startedAt timestamp and a new Turn with the attacker and defender players.

path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "game": {
    }
}

Roll the dice for a turn

Rolls the die for the player, and returns the result.

If this is the last roll of the turn (both players have rolled), the game will be updated with the result of the damage dealt. If the defending player died, the winner will be declared in the Game object. Otherwise, a new Turn will be created with the attacker and defender roles switched.

path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
playerId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "playerId": "35184259-d156-4290-94ed-3a4b4f2c36f8"
}

Response samples

Content type
application/json
{
  • "roll": 1,
  • "game": {
    }
}