This isn't official or anything, but it should be a little easier than having to actually browse the backend code.

Requests

All requests sent to the API must have the following schema:

{
    "request_type" : "foo",
    "other_field1" : "bar",
    "other_field2" : {
        "baz" : "quux",
        "spam" : "eggs"
    }
}

where "foo" is the type of request, and the "other_field" keys are other data that may be required.

The API doesn't care about extra fields; they'll just be ignored. Missing a field that is required, however, will get you a JSONInvalidMessageReponse, though.

Gameroom API

The Gameroom is a room where you can request a list of the active games in progress, create a gain, or join a game. All other requests will get you a JSONInvalidMessageResponse.

get_games

Requests a list of the active games in progress. Returns a list of tuples. The first element of each tuple is the game ID. The second element is the current state of the game.

TODO: This should probably be an object that associates game IDs (keys) with game objects (values).

Example request:

{
    "request_type" : "get_games"
}

Example response:

{
    "response_type":"active_games",
    "games": [
        [
            "lDrCjIqHScSEOpJ", {
                "blackID":"pogtastic",
                "boardState": {
                    "board":[3,3,3,3,3,3,3,3,3,3,3,3,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,1],
                    "gameState": {
                        "currentState":"RegularTurn",
                        "color":2
                    }
                }
            }
        ]
    ]
}

create_game

Creates a game, with the requester as Black.

Example request:

{
    "request_type" : "create_game"
}

Example response:

{
    "response_type":"created_game",
    "board_state": {
        "board":[3,3,3,3,3,3,3,3,3,3,3,3,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,1],
        "gameState": {
            "currentState":"RegularTurn",
            "color":2
        }
    }
}

join_game

Joins a game in progress. You must provide the gameID of the game you want to access.

TODO: Make gameID camel_case to be consistent? Sorry.

Example request:

{
    "request_type" : "join_game", 
    "gameID" : "lDrCjIqHScSEOpJ"
}

Example response:

{
    "response_type":"joined_game",
    "board_state": {
        "board":[3,3,3,3,3,3,3,3,3,3,3,3,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,1],
        "gameState": {
            "currentState":"RegularTurn",
            "color":2
        }
    }
}

join_game

Joins a game in progress as a spectator. You must provide the gameID of the game you want to access.

Example request:

{
    "request_type" : "spectate_game", 
    "gameID" : "lDrCjIqHScSEOpJ"
}

Example response:

{
    "response_type":"spectated_game",
    "board_state": {
        "board":[3,3,3,3,3,3,3,3,3,3,3,3,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,1],
        "gameState": {
            "currentState":"RegularTurn",
            "color":2
        }
    }
}

Game

So, you've joined a game. You can do exactly two things right now.

get_state

Gets the current board state.

Example request:

{
    "request_type" : "get_state"
}

Example response:

{
    "response_type":"board_state",
    "red_id":"pog2",
    "black_id":"pogtastic",
    "board_state": {
        "board":[3,3,3,3,3,3,3,3,3,3,3,3,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,1],
        "gameState": {
            "currentState":"RegularTurn",
            "color":2
        }
    }
}

move

Sends a move to the server. Sending a valid move will get you a JSONValidMoveResponse. Sending an invalid move will get you a JSONInvalidMoveResponse.

Example request:

{
    "request_type" : "move", 
    "move" : {
        "source" : 8, 
        "target" : 13
    }
}

Example valid_move response:

{
    "response_type":"valid_move",
    "board_state": {
        "board":[3,3,3,3,3,3,3,3,0,3,3,3,0,3,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,1],
        "gameState": {
            "currentState":"RegularTurn",
            "color":1
        }
    }
}

Example invalid_move response:

{
    "response_type":"invalid_move",
    "board_state": {
        "board":[3,3,3,3,3,3,3,3,0,3,3,3,0,3,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,1],
        "gameState": {
            "currentState":"RegularTurn",
            "color":1
        }
    }
}

leave_game

As a spectator, you can leave a game and rejoin the game room. The game will unsubscribe the socket from the game and subscribe it to the game room's API.

Example request:

{
    "request_type" : "leave_game"
}