Verb | URI Pattern | Controller#Action |
---|---|---|
POST | /login |
users#login |
POST | /register |
users#create |
GET | /games |
games#index |
POST | /games |
games#create |
GET | /games/:id |
games#show |
PATCH | /games/:id |
games#update |
GET | /games/:id/watch |
games#watch |
All API actions, except watch
, expect data in the request body to be JSON, Content-Type:application/json; charset=utf-8
, and return data, if any, as JSON in the response body.
Summary:
Request | Response | |||
---|---|---|---|---|
Verb | URI | body | Status | body |
POST | `/login` | credentials | 200, OK | token |
401, Unauthorized | empty | |||
POST | `/register` | credentials | 201, Created | user |
400, Bad Request | empty |
The login
action expects a POST with credentials
identifying a previously registered user, e.g.:
{
"credentials": {
"email": "an@example.email",
"password": "an example password"
}
}
If the request is successful, the response will have an HTTP Status of 200, OK, and the body will be JSON containing a token used to authenticate other requests, e.g.:
{
"token": "an example authentication token"
}
If the request is unsuccessful, the response will have an HTTP Status of 401, Unauthorized, and the response body will be empty.
The create
action expects a POST of credentials
identifying a new user to create, e.g.:
{
"credentials": {
"email": "an@example.email",
"password": "an example password",
"password_confirmation": "an example password"
}
}
If the request is successful, the response will have an HTTP Status of 201, Created, and the body will be JSON containing the id
and email
of the new user, e.g.:
{
"id": 1,
"email": "an@example.email"
}
If the request is unsuccessful, the response will have an HTTP Status of 400, Bad Request, and the response body will be empty.
All games action requests must include a valid HTTP header Authorization: Token token=<token>
or they will be rejected with a status of 401, Unauthorized.
Games are associated with users, player_x
and player_o
. Actions, other than update, will only retrieve a game if the user associated with the Authorization
header is one of those two users. If this requirement is unmet, the response will be 404, Not Found, except for the index action which will return an empty games array.
Summary:
Request | Response | |||
---|---|---|---|---|
Verb | URI | body | Status | body |
GET | `/games[?over=]` | n/a | 200, OK | games found |
The optional `over` query parameter restricts the response to games with a matching `over` property. | 200, OK | empty games | ||
The default is to retrieve all games associated with the user.. | 401, Unauthorized | empty | ||
POST | `/games` | n/a | 201, Created | game created |
401, Unauthorized | empty | |||
400, Bad Request | errors | |||
GET | `/games/:id` | n/a | 200, OK | game found |
401, Unauthorized | empty | |||
404, Not Found | empty | |||
PATCH | `/games/:id` | empty | 200, OK | game joined |
400, Bad Request | errors | |||
400, Bad Request | empty | |||
PATCH | `/games/:id` | game delta | 200, OK | game updated |
400, Bad Request | errors | |||
404, Not Found | empty |
The index
action is a GET that retrieves all the games associated with a user. The response body will contain JSON containing an array of games, e.g.:
{
"games": [
{
"id": 1,
"cells": ["o","x","o","x","o","x","o","x","o"],
"over": true,
"player_x": {
"id": 1,
"email": "and@and.com"
},
"player_o": {
"id": 3,
"email": "dna@dna.com"
}
},
{
"id": 2,
"cells": ["","","","","","","","",""],
"over": false,
"player_x": {
"id": 3,
"email": "dna@dna.com"
},
"player_o": {
"id": 1,
"email": "and@and.com"
}
}
]
}
If the over
query parameter is specified the results will be restricted accordingly.
If there are no games associated with the user, the response body will contain an empty games array, e.g.:
{
"games": [
]
}
The create
action expects a POST with an empty request body. If the request is successful, the response will have an HTTP Status of 201, Created, and the body will contain JSON of the created game with player_x
set to the user calling create
, e.g.:
{
"game": {
"id": 3,
"cells": ["","","","","","","","",""],
"over": false,
"player_x": {
"id": 1,
"email": "and@and.com"
},
"player_o": null
}
}
If the request is unsuccessful, the response will have an HTTP Status of 400, Bad Request, and the response body will be JSON describing the errors.
The show
action is a GET specifing the id
of the game to retrieve. If the request is successful the status will be 200, OK, and the response body will contain JSON for the game requested, e.g.:
{
"game": {
"id": 1,
"cells": ["o","x","o","x","o","x","o","x","o"],
"over": true,
"player_x": {
"id": 1,
"email": "and@and.com"
},
"player_o": {
"id": 3,
"email": "dna@dna.com"
}
}
}
This update
action expects an empty PATCH, to join an existing game.
If the request is successful, the response will have an HTTP Status of 200, OK, and the body will be JSON containing the game joined, e.g.:
{
"game": {
"id": 1,
"cells": ["","","","","","","","",""],
"over":false,
"player_x": {
"id": 1,
"email": "and@and.com"
},
"player_o": {
"id": 3,
"email":
"dna@dna.com"
}
}
}
If the request is unsuccessful, the response will have an HTTP Status of 400, Bad Request, and the response body will be empty (game cannot be joined, player_o already set or user making request is player_x) or JSON describing the errors.
This update
action expects a PATCH with changes to to an existing game, e.g.:
{
"game": {
"cell": {
"index": 0,
"value": "x"
},
"over": false
}
}
If the request is successful, the response will have an HTTP Status of 200, OK, and the body will be JSON containing the modified game, e.g.:
{
"game": {
"id": 1,
"cells": ["x","","","","","","","",""],
"over":false,
"player_x": {
"id": 1,
"email": "and@and.com"
},
"player_o": {
"id": 3,
"email":
"dna@dna.com"
}
}
}
If the request is unsuccessful, the response will have an HTTP Status of 400, Bad Request, and the response body will be JSON describing the errors.
The watch
action is handled differently than all the others. Because watch
implements a streaming source of data, we'll use a wrapper around the html5 object EventSource.
You can find this wrapper in the https://github.com/ga-wdi-boston/jquery-ajax-post-patch-fe repository.
You create a watcher object using the resourceWatcher function. This function takes two parameters, the watch url and a configuration object which must contain the Authorization token, and may contain an optional timeout in seconds, e.g.:
var gameWatcher = resourceWatcher('<server>/games/:id/watch', {
Authorization: 'Token token=<token>'[,
timeout: <timeout>]
});
The watched resource has a default timeout of 120 seconds.
You should add a handler for change
and error
events. The error events are not the most informative. The change event may return a timeout.
game.on('change', function(d){
var data = JSON.parse(d);
if (data.timeout) { //not an error
game.close();
return console.warn(data.timeout);
}
var gameData = data.game;
var cell = gameData.cell;
var index = cell.index
var value = cell.value;
});
game.on('error', function(e){
console.error(e);
});