Retrieve Results of a Dice Roll

Rolls 10-sided dice against a difficulty and returns the results.

URL

GET http://localhost:4567/api/v1/roll

Query Parameters

ParameterDescriptionTypeRequiredNotes
num_diceNumber of 10-sided dice to roll.intRequired
difficultyThe number each die must meet or beat to succeed.intOptionalDefault value is 6

Sample Request

GET http://localhost:4567/api/v1/roll?numDice=4&difficulty=7

Response

ElementDescriptionTypeNotes
difficultyThe number the API compared dice to for success.numberBetween 2 and 10
num_diceHow many dice the API rolled.number
facesThe result of rolling the dice. One die for each num_dice.array of numbersDice are 10-sided
rolled_successesThe number of dice that met or beat the difficultynumber
rolled_onesHow many 1s are in the result.number
total_successesThe rolled successes minus the rolled ones.number
outcomeThe overall outcome of the roll.stringValid values: "success", "failure", "botch"

Sample Response

{
  "difficulty":5,
  "num_dice":4,
  "faces":[8,9,8,1],
  "rolled_successes":3,
  "rolled_ones":1,
  "total_successes":2,
  "outcome": "success"
}

Status Codes and Errors

The following table lists the returned HTTP status codes.

CodeDescriptionNotes
200OK
400Bad RequestA query parameter is invalid