API server back-end for Backbone.js Tic-Tac-Toe apps created as part of the Ada Developers Academy curriculum.
The Tic-Tac-Toe API is responsible for tracking a history of played games. Each game is recorded on the server with its final game board (the location of each X or O on the board), the game outcome (win or draw), the date when the game was completed, and the names of the participants.
The API communicates solely through JSON-encoded messages and provides four routes for working with Game data:
- List all games - Retrieves an index of all recorded
Games. Each entry in the response array is a summary of the games (it does not include the final game board). - Game details - Retrieves the complete details of a single
Game, including the final game board. - Create a game - Records a new, completed
Game. Details of the game (as specified below) must be sent as a JSON-encoded document. - Delete a game - Removes a previously recorded
Gamefrom the API.
This API only has a single model, Game, with the following properties:
id- A positive integer that uniquely identifies the game within this API. NOTE: WhenPOSTing a new game to the API this property is ignored if it was supplied.board- An array of strings, exactly 9 elements long. Each string within the array is either"X","O", or" "(blank) and corresponds to the contents of a specific cell on the game board. The array is two dimensional in row-major order (see diagram below for clarification).players- An array of strings, exactly 2 elements long. Each string corresponds to the name of a single player for this game. The first element is always the player represented by X on the board, and the second element is always the player represented by O on the board. NOTE: The second player's name is strictly optional, and will default to"Anonymous"if unspecified whenPOSTing a new game to the API.outcome- A string representing the result of the game. The only valid values are"X"(for X winning),"O"(for O winning), and"draw"(for a tie).played_at- A date & time representing when the game was completed and recorded by the API. Because JSON does not have a built-in date datatype this property is encoded as a string using the ISO 8601 format. NOTE: This property is optional whenPOSTing a new game to the API. The server will use the current date & time if one is not provided.
An example of a complete Game model encoded in JSON:
{
"id": 1,
"board": [
"X",
" ",
"O",
"X",
"O",
" ",
"X",
" ",
" "
],
"players": [
"X Player",
"O Player"
],
"outcome": "X",
"played_at": "2016-11-20T22:59:10Z"
}This data corresponds to the following final game board between two players, X Player and O Player:
| X | O | |
| X | O | |
| X |
The array of strings for board in the Game model is mapped to locations on the Tic-Tac-Toe game board using zero indexing:
| 0 | 1 | 2 |
| 3 | 4 | 5 |
| 6 | 7 | 8 |
When a request is made to the API that results in an error with user-meaningful details, those details will be communicated in the response data using the following form:
{
"errors": [
"Error message 1",
"Error message 2",
...
"Error message N"
]
}This is a complete reference to the Tic-Tac-Toe API version 1. All request and response data must be encoded in JSON.
GET /api/v1/games
None.
None.
The status code for a successful request will be 200.
A list of Game objects. Each Game object will only have the "summary" information for that game, meaning it will not include the board property.
The following status codes may be returned in the event of an error:
500in the event of an unexpected server error.
GET /api/v1/games/{game_id}
The ID of an existing game. This value must be acquired by first requesting a list of games and using one of the IDs from within that list.
None.
The status code for a successful request will be 200.
A single Game object. This object has the complete details for the game, including the board property.
The following status codes may be returned in the event of an error:
404when the requestedGameis not found.500in the event of an unexpected server error.
POST /api/v1/games
None.
A single Game object, without the id property.
The status code for a successful request will be 201.
A single Game object (the one that was created). This object has the complete details for the game, including the board property.
The following status codes may be returned in the event of an error:
400when the providedGameproperties are invalid. The response data will be anErrorobject with strings for each failed validation.500when theGamewas not saved due to an unexpected server error.
DELETE /api/v1/games/{game_id}
The ID of an existing game. This value must be acquired by first requesting a list of games and using one of the IDs from within that list.
None.
The status code for a successful request will be 204.
None.
The following status codes may be returned in the event of an error:
404when the requestedGameis not found.500in the event of an unexpected server error.
- Fork and clone this repository to your own account
- Run
bundle installto download gem dependencies
- If you do not have Postgres installed on your development machine, run
bundle install --without productioninstead.
- Run
rails serverto start the development server. - Run
rails consoleto access a REPL running in the Rails context.
Run rails test to run the full test suite.
This API can be deployed to Heroku with the following commands (assuming you have the Heroku CLI installed):
$ heroku create
$ heroku run bundle exec rails db:schema:load
$ heroku openThe last command will open a browser window with your API endpoint as the URL. This API is not designed to be meaningful to people accessing it via the browser, but it does give you the correct hostname to use when integrating your deployed instance into other applications.