EN605.607.81.SP22_ASDM_Project/specifications/backend_protocol_specification.md
Stephen Seo b2ea79a7f7 Impl conditionally update front-end board
When the front-end polls the back-end for the game-state, the back-end includes
a "date_updated" String in the JSON. If the String is the same as in the
front-end, then no updates are needed, but if they are not the same, then the
front-end will update the board. Because the front-end polls the back-end's
board state approximately every second, this should make the front-end more
efficient.
2022-04-30 16:44:48 +09:00

4.2 KiB

Backend Protocol

The backend will be available at https://asdm.seodisparate.com/api .
The frontend will send http 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",
    }

An optional "phrase" parameter can be sent to match against other players with the same "phrase".

    {
        "type": "pairing_request",
        "phrase": "user_defined_phrase",
    }
  1. Check pairing status
    {
        "type": "check_pairing",
        "id": "id given by backend",
    }
  1. Request Turn action
    {
        "id": "id given by backend",
        "type": "place_token",
        "position": 7,
    }
  1. Disconnect
    {
        "id": "id given by backend",
        "type": "disconnect",
    }
  1. Request Game State:
    {
        "id": "id given by backend",
        "type": "game_state",
    }
  1. Chat Emote Send:
    {
        "id": "id given by backend",
        "type": "send_emote",
        "emote": "smile", // or "frown", or "neutral", or "think"
    }

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"
    }
  1. Check pairing status
    {
        "type": "pairing_status",
        "status": "waiting", // or "unknown_id"
    }
    {
        "type": "pairing_status",
        "status": "paired",
        "color": "magenta", // or "cyan"
    }   
  1. Request Turn action Response
    {
        "type": "place_token",
        "status": "not_paired_yet", // or "accepted", "illegal",
                                    // "not_your_turn", "game_ended_draw",
                                    // "game_ended_cyan_won",
                                    // "game_ended_magenta_won", "unknown_id"
        "board": "abcdefg..."       // see protocol 5 response for details
    }   
  1. Disconnect Response
    {
        "type": "disconnect",
        "status": "ok", // or "unknown_id"
    }
  1. 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 winning piece
                              // e - magenta winning piece
                              // f - cyan placed
                              // g - magenta placed
                              // h - cyan winning and placed piece
                              // i - magenta winning and placed piece
        // optional "peer_emote" entry is message from opponent
        "peer_emote": "smile",// or "frown", or "neutral", or "think"

        // should always be available when "board" is available
        "updated_time": "2022-04-30 12:00:00"
    }
  1. Send Emote Request Response
    {
        "type": "send_emote",
        "status": "ok", // or "invalid_emote", "peer_disconnected",
                        // "internal_error"
    }

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