=========
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.