EN605.607.81.SP22_ASDM_Project/backend_protocol_specification.md

Backend Protocol

The backend will be available at https://asdm.seodisparate.com/api .
The frontend will send http GET/POST requests to the URL with JSON as the body of the request, and the backend will respond with JSON.

Requests

1. Request ID and Pairing

    {
        "type": "pairing_request",
    }

2. Check pairing status

    {
        "type": "check_pairing",
        "id": "id given by backend",
    }

3. Request Turn action

    {
        "id": "id given by backend",
        "type": "place_token",
        "position": 7,
    }

4. Disconnect

    {
        "id": "id given by backend",
        "type": "disconnect",
    }

5. Request Game State:

    {
        "id": "id given by backend",
        "type": "game_state",
    }

Responses

1. Request ID Response

    {
        "type": "pairing_response",
        "id": "id set by backend",
        "status": "waiting",
    }

    {
        "type": "pairing_response",
        "id": "id set by backend",
        "status": "paired",
        "color": "cyan", // or "magenta"
    }

If there are too many players such that a new game cannot be feasibly started, then the back-end will respond with "too_many_players".

    {
        "type": "pairing_response",
        "status": "too_many_players"
    }

2. Check pairing status

    {
        "type": "pairing_response",
        "status": "waiting", // or "unknown_id"
    }

    {
        "type": "pairing_response",
        "status": "paired",
        "color": "magenta", // or "cyan"
    }   

3. Request Turn action Response

    {
        "type": "place_token",
        "status": "not_paired_yet", // or "accepted", "illegal",
                                    // "not_your_turn", "game_ended",
                                    // "unknown_id"
    }   

4. Disconnect Response

    {
        "type": "disconnect",
        "status": "ok", // or "unknown_id"
    }

5. Request Game State Response

    {
        "type": "game_state",
        "status": "not_paired", // or "unknown_id", "cyan_turn", "magenta_turn",
                                // "cyan_won", "magenta_won", "draw",
                                // "opponent_disconnected", "internal_error"

        // "board" may not be in the response if "unknown_id" is the status
        "board": "abcdefg..." // 56-char long string with mapping:
                              // a - empty
                              // b - cyan
                              // c - magenta
                              // d - cyan placed
                              // e - magenta placed
                              // f - cyan winning piece
                              // g - magenta winning piece
    }

Note that the backend will stop keeping track of the game once both players have successfully requested the Game State once after the game has ended. Thus, future requests may return "unknown_id" as the "status".

Note that if a player has disconnected, the other player will receive a "status" of "opponent_disconnected". Future requests will return "unknown_id".