========= TicTacToe

This is a demo application designed to demonstrate interfacing a mobile device with a server.

Board

a) 0|1|2 b) O| |X

3|4|5 |O|X

6|7|8 X| |

The board is represented as a string of characters, where each spot may be either a blank (_), an X, or an O. Thus the board (b) above, may be shown as:

"O_X_OXX__"

Protocol

A HTTP request is denoted as a right-arrow (-->), whereas the response is a left-arrow (<--). Notifications are denoted by !!!.

The client must first establish a session with the server:

--> /api/play client_id=920d14a9a2204d8bbc553ef94f6d6773&name=stan <-- {"client_id": "920d14a9a2204d8bbc553ef94f6d6773", "name": "stan", "game_id": "eZUcx"}

!!! {"type": "status", "board": "_________", "turn": "X", "playerX": "stan", "playerO": "kyle", "cursor": 1, "timestamp": "2011-06-05T06:26:27.088843"}

!!! {"type": "connect", "name": "stan", "player": "X", "cursor": 2, "timestamp": "2011-06-05T06:26:27.088843"}

!!! {"type": "connect", "name": "kyle", "player": "O", "cursor": 3, "timestamp": "2011-06-05T06:26:27.088843"}

At this point the clients should connect to the server to receive notifications on their new game:

--> /api/updates/{game_id}

X plays first:

--> /api/move client_id=920d14a9a2204d8bbc553ef94f6d6773&position=2

!!! {"type": "move", "board": "X____", "turn": "O", "player": "X", "position": 2, "cursor": 10, "timestamp": "2011-06-05T06:26:27.088843"}

--> /api/move client_id=7c288e7e8c1341ce9f11b9aaf0e1a6de&position=0

!!! {"type": "move", "board": "O_X______", "turn": "X", "player": "O", "position": 2, "cursor": 12, "timestamp": "2011-06-05T06:26:27.088843"}

...

--> /api/move client_id=7c288e7e8c1341ce9f11b9aaf0e1a6de&position=8

!!! {"type": "move", "board": "O_X_OXX_O", "winner": "O", "player": "O", "position": 8, "cursor": 15, "timestamp": "2011-06-05T06:26:27.088843"}

!!! {"type": "disconnect", "name": "kyle", "player": "O", "cursor": 20, "timestamp": "2011-06-05T06:26:27.088843"}

Methods

POST requests should have a Content-Type:

application/x-www-form-urlencoded

GET requests must have their params in the querystring of the url.

Methods have a success response, as well as potential error responses. All responses are JSON-encoded.

Error responses are accompanied by a corresponding HTTP status code in the 4xx or 5xx range and a possible dictionary containing the error code and message in the format:

{
    'error': {
        'code': 1234,
        'message': 'You broke it!'
    }
}

It is safe for the client to assume that if the 'error' key is present in the response, the request was not successful.

/api/play

Method: POST Params: client_id (optional) Identifier for the client. This will uniquely identify the client and if left blank will be randomly generated by the server. The identifier can be used later to resume a session. name (optional) Identifier for user. Will be randomly assigned if unspecified. resume (optional) Boolean "true" or "false" signifying whether to attempt to resume a previous game. If this is "true" and there are no games to resume, this will fail. Defaults to "false". Response: client_id The specified client identifier if provided, otherwise a new randomly generated identifier from the server. name The specified user name if provided, otherwise a new randomly generated name from the server (Guest1234). game_id Identifier used when connecting to the server to receive notifications.

/api/quit

Method: POST Params: client_id Identifier for the client.

/api/move

Method: POST Params: client_id Identifier for the client. position A digit between 0 and 8 signifying where the piece was placed. Response: none

/api/chat

Method: POST Params: client_id Identifier for the client. message A string from the client. Response: none

/api/updates/{game_id}

Method: GET Params: cursor (optional) The cursor is used to avoid missing updates between requests. If left unspecified the events will be replayed back from the start of the game in order. Otherwise, only events after the cursor will be replayed.

Connect Updates
~~~~~~~~~~~~~~~
type - "connect"
timestamp
    Timestamp for this update in ISO format (UTC).
cursor
    Integer representing this update. This is used such that clients can
    resume updates at the point they left off.
name
    Name of player connecting to the game.
player
    true or false depending on whether the client is a player.

Disconnect Updates
~~~~~~~~~~~~~~~~~~
type - "disconnect"
timestamp
    Timestamp for this update in ISO format (UTC).
cursor
    Integer representing this update. This is used such that clients can
    resume updates at the point they left off.
name
    Name of player disconnecting from the game.
player
    true or false depending on whether the client is a player.

Status Updates
~~~~~~~~~~~~~~
type - "status"
timestamp
    Timestamp for this update in ISO format (UTC).
cursor
    Integer representing this update. This is used such that clients can
    resume updates at the point they left off.
board
    The board state, as described in the "Board" section above.
turn
    'X' or 'O' signifying whose turn it currently is.
playerX
    Name of 'X' player.
playerO
    Name of 'O' player.

Board Updates
~~~~~~~~~~~~~
type - "move"
timestamp
    Timestamp for this update in ISO format (UTC).
cursor
    Integer representing this update. This is used such that clients can
    resume updates at the point they left off.
board
    The board state, as described in the "Board" section above.
player
    The player who caused this update.
position
    The position on the board entered by the player.
turn (optional)
    'X' or 'O' signifying whose turn it currently is.
winner (optional)
    'X' or 'O' or 'D' signifying who has won the game. A draw
    (or cat's game) is denoted by a D.

One of "turn" or "winner" will be specified.

Chat Updates
~~~~~~~~~~~~
type - "chat"
timestamp
    Timestamp for this update in ISO format (UTC).
cursor
    Integer representing this update. This is used such that clients can
    resume updates at the point they left off.
name
    The name of the player writing the message.
message
    A message string.

Terminal Updates
~~~~~~~~~~~~~~~~
type - "end"
timestamp
    Timestamp for this update in ISO format (UTC).
cursor
    Integer representing this update. This is used such that clients can
    resume updates at the point they left off.
reason
    Various reasons, but probably because one client quit or the game is
    complete. Every game will contain a terminal update when it is over.