All API calls are simple HTTP GET requests, with various key/value pairs passed in as part of the query string.
API Endpoint
The reference implementation of the API can be accessed at http://52.35.157.11/hw6/server.php from anywhere.
All API responses are JSON encoded messages, sent with a Content-Type of text/json.
An example API request and response:
server.php?cmd=stats
{
"message": "stats",
"data": {
"switchWins": "15",
"switchLoss": "9",
"noSwitchWins": "4",
"noSwitchLoss": "10"
}
}
Here the full request URL for the reference API server would be http://52.35.157.11/hw6/server.php?cmd=stats and the response is shown. The reference API server displays "pretty printed" JSON, but this is not required if you are implementing the API, as it is not a built-in feature of all PHP versions.
Successful Commands
Successful commands will be returned with an HTTP code of 200. The JSON response will be an object. Successful responses will have a "message" property which will contain a descriptive message about what's going on. It may return other properties as well depending on the API Command.
Errors
Certain commands may return errors depending on the situation. This most often occurs when an incomplete or invalid command is given. Errors are reported back with HTTP codes of 400-499 depending on the error. The JSON response will contain an "error" property, which is a descriptive string describing the error.
{
"error": "invalid command"
}
API Commands
newGame
The newGame command will create a new game in the database, and return basic game data. The most important thing returned is the game_id, required for all subsequent API calls.
REQUEST
- cmd=newGame
RESPONSE
- message: "new game created"
- data: game data
server.php?cmd=newGame
{
"message": "new game created",
"data": {
"game_id": "5",
"opened_door": null,
"initial_selected": null,
"final_selected": null
}
}
firstChoice
The firstChoice command will enter the Player's first choice of door. The Server will respond with updated game data, with opened_door being ID of the door the Host will open to show no prize.
REQUEST
- cmd=firstChoice
- game_id=[id of game]
- choice=[door number chose (zero based indexes)]
RESPONSE
- message: "opened door"
- data: game data
server.php?cmd=firstChoice&game_id=5&choice=0
{
"message": "opened door",
"data": {
"game_id": "5",
"opened_door": "1",
"initial_selected": "0",
"final_selected": null
}
}
server.php?cmd=firstChoice
{
"error": "game_id parameter is required"
}
server.php?cmd=firstChoice&game_id=5
{
"error": "choice parameter is required"
}
server.php?cmd=firstChoice&game_id=ABC&choice=0
{
"error": "game_id must be an integer"
}
server.php?cmd=firstChoice&game_id=5&choice=ABC
{
"error": "choice must be an integer"
}
server.php?cmd=firstChoice&game_id=8271761&choice=0
{
"error": "no matching game found"
}
finalChoice
The finalChoice command will enter the final choice of the Player for their chosen door. The Server will respond with wether or not the Player has won, as well as the final game state, including the correct door the prize was behind.
REQUEST
- cmd=finalChoice
- game_id=[id of game]
- choice=[door number chose (zero based indexes)]
RESPONSE
- message: "you won" or "you lost"
- gameID: final game data
server.php?cmd=finalChoice&game_id=5&choice=2
{
"message": "you won",
"data": {
"game_id": "5",
"prize_door": "0",
"opened_door": "1",
"initial_selected": "0",
"final_selected": "2"
}
}
server.php?cmd=finalChoice&game_id=5&choice=1
{
"error": "cannot choose opened door"
}
server.php?cmd=finalChoice
{
"error": "game_id parameter is required"
}
server.php?cmd=finalChoice&game_id=5
{
"error": "choice parameter is required"
}
server.php?cmd=finalChoice&game_id=ABC&choice=0
{
"error": "game_id must be an integer"
}
server.php?cmd=finalChoice&game_id=5&choice=ABC
{
"error": "choice must be an integer"
}
server.php?cmd=finalChoice&game_id=8271761&choice=0
{
"error": "no matching game found"
}
stats
The stats command will return data about how may games have been won and lost, depending on wether the Player switched their choice or not.
REQUEST
- cmd=stats
RESPONSE
- message: "stats"
- data: game stats
server.php?cmd=stats
{
"message": "stats",
"data": {
"switchWins": "15",
"switchLoss": "9",
"noSwitchWins": "4",
"noSwitchLoss": "10"
}
}