openapi.yaml

openapi: 3.0.1
info:
  title: Kilo API
  description: >
    The following is the API specification for
    [Kilo](https://kilo-games.netlify.app/)
  # termsOfService: http://swagger.io/terms/
  # contact:
  #   email: apiteam@swagger.io
  license:
    name: Dual MIT/Apache 2.0
    url: https://github.com/search?q=repo%3ATeamKilo%2Fkilo_server+filename%3ALICENSE&type=Code
  version: 1.0.0
servers:
  - url: https://team-kilo-server.herokuapp.com/api
tags:
  - name: Game management
    description: Game creation and searching
  - name: Game
    description: Game viewing and playing
paths:
  /create-game:
    post:
      tags:
        - Game management
      summary: Create a game
      description: Create a game given a type of game
      operationId: createGame
      requestBody:
        content:
          application/json:
            schema:
              required:
                - game_type
              type: object
              properties:
                game_type:
                  $ref: '#/components/schemas/GameType'
        required: true
      responses:
        200:
          description: Game successfully added
          content:
            application/json:
              schema:
                required:
                  - game_id
                type: object
                properties:
                  game_id:
                    $ref: '#/components/schemas/GameId'
          links:
            Join game:
              $ref: '#/components/links/GameIdJoinGame'
            Get state:
              $ref: '#/components/links/GameIdGetState'
            Submit move:
              $ref: '#/components/links/GameIdSubmitMove'
        400:
          description: JSON deserialization error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/JSONDeserializeError'
  /list-games:
    get:
      tags:
        - Game management
      summary: List existing games
      description: >
        List the ID, game type, players, stage and last updated time of up to 20
        existing games and give the total number of existing games
      operationId: listGames
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
          description: >
            The page of the pagination of game summaries, with the first page
            having the first 20 results, the second having the next 20 and so
            on
          required: false
        - in: query
          name: sort_order
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          description: >
            Whether the results are sorted in **asc**ending or **desc**ending
            order, where ascending is from A to Z
          required: false
        - in: query
          name: sort_key
          schema:
            type: string
            enum:
              - game_type
              - players
              - stage
              - last_updated
            default: last_updated
          description: >
            What the game summary list is sorted by

            - `game_type` - Sort by the type of game

            - `players` - Sort by the number of players

            - `stage` - Sort by the game stage

            - `last_updated` - Sort by the time the game was lasted updated

            Game summaries with equal values for each key are sorted by the
            following key in the above list
          required: false
        - in: query
          name: game_type
          schema:
            $ref: '#/components/schemas/GameType'
          description: >
            If this is parameter present, only games of this type are
            searched for
          required: false
        - in: query
          name: players
          schema:
            type: integer
            minimum: 0
          description: >
            If this is parameter present, only games with this number
            of players are searched for
          required: false
        - in: query
          name: stage
          schema:
            $ref: '#/components/schemas/Stage'
          description: >
            If this is parameter present, only games in this stage are
            searched for
          required: false
      responses:
        200:
          description: A list of game summaries and the number of games existing
          content:
            application/json:
              schema:
                type: object
                required:
                  - game_summaries
                  - number_of_games
                properties:
                  game_summaries:
                    type: array
                    description: A list of game summaries
                    items:
                      allOf:
                        - type: object
                          required:
                            - game_id
                            - game_type
                          properties:
                            game_id:
                              $ref: '#/components/schemas/GameId'
                            game_type:
                              $ref: '#/components/schemas/GameType'
                        - $ref: '#/components/schemas/GameSummaryBase'
                  number_of_games:
                    type: number
                    description: The number of games existing
                    minimum: 0
        400:
          description: Query deserialization error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/QueryDeserializeError'
  /{game_id}/join-game:
    post:
      tags:
        - Game
      summary: Join a game
      description: Attempt to join a game, creating a session
      operationId: joinGame
      parameters:
        - in: path
          name: game_id
          schema:
            $ref: '#/components/schemas/GameId'
          required: true
          description: ID of a game
      requestBody:
        content:
          application/json:
            schema:
              required:
                - username
              type: object
              properties:
                username:
                  $ref: '#/components/schemas/Username'
        required: true
      responses:
        200:
          description: Session successfully created
          content:
            application/json:
              schema:
                required:
                  - session_id
                type: object
                properties:
                  session_id:
                    $ref: '#/components/schemas/SessionId'
          links:
            Submit move:
              $ref: '#/components/links/SessionIdSubmitMove'
        400:
          description: >
            Path deserialization error, username is invalid or game has already started
          content:
            text/plain:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PathDeserializeError'
                  - $ref: '#/components/schemas/InvalidUsername'
                  - $ref: '#/components/schemas/GameInProgress'
        404:
          description: Game not found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/GameNotFound'
  /{game_id}/get-state:
    get:
      tags:
        - Game
      summary: Get a game's state
      description: >
        Get a game's state, including the current players, the stage, the
        players that have won so far, the type of the game and a
        game-specific payload with additional information
      operationId: getState
      parameters:
        - in: path
          name: game_id
          schema:
            $ref: '#/components/schemas/GameId'
          required: true
          description: ID of a game
      responses:
        200:
          description: The game's state
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/GameSummaryBase'
                  - type: object
                    required:
                      - can_move
                      - winners
                      - game_name
                      - payload
                    properties:
                      players:
                        type: array
                        items:
                          $ref: '#/components/schemas/Username'
                        description: The usernames of players currently in the game
                        example:
                          - Player 1
                          - Player 2
                      stage:
                        type: string
                        enum:
                          - waiting
                          - in_progress
                          - ended
                        description: >
                          Whether the game is waiting for players, in progress or
                          over
                        example: in_progress
                      can_move:
                        type: array
                        items:
                          $ref: '#/components/schemas/Username'
                        description: >
                          Usernames from `players` that can use
                          `POST /{game_id}/submit-move/`
                      winners:
                        type: array
                        items:
                          $ref: '#/components/schemas/Username'
                        description: >
                          Usernames from `players` that are winners
                          (this is empty if there is a draw)
                        example: [ ]
                      payload:
                        oneOf:
                          - $ref: '#/components/schemas/Connect4Request'
                          - $ref: '#/components/schemas/SnakeRequest'
                        discriminator:
                          propertyName: game_type
        400:
          description: Path or JSON deserialization error
          content:
            text/plain:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PathDeserializeError'
                  - $ref: '#/components/schemas/JSONDeserializeError'
        404:
          description: Game not found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/GameNotFound'
  /{game_id}/submit-move:
    post:
      tags:
        - Game
      summary: Submit a move
      description: >
        Attempt to submit a player's move in a game
      operationId: submitMove
      requestBody:
        content:
          application/json:
            schema:
              required:
                - session_id
                - payload
              type: object
              properties:
                session_id:
                  $ref: '#/components/schemas/SessionId'
                payload:
                  oneOf:
                    - $ref: '#/components/schemas/Connect4Response'
                    - $ref: '#/components/schemas/SnakeResponse'
                  discriminator:
                    propertyName: game_type
        required: true
      parameters:
        - in: path
          name: game_id
          schema:
            $ref: '#/components/schemas/GameId'
          required: true
          description: ID of a game
      responses:
        200:
          description: Move successfully made
          content:
            application/json:
              schema:
                required:
                  - clock
                type: object
                properties:
                  clock:
                    $ref: '#/components/schemas/SessionId'
        400:
          description: >
            Path or JSON deserialization error, game is not in progress,
            session does not match game, move is invalid or player cannot
            currently move
          content:
            text/plain:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PathDeserializeError'
                  - $ref: '#/components/schemas/JSONDeserializeError'
                  - $ref: '#/components/schemas/GameWaiting'
                  - $ref: '#/components/schemas/GameEnded'
                  - $ref: '#/components/schemas/InvalidMove'
                  - $ref: '#/components/schemas/InvalidPlayer'
        404:
          description: Game or session not found
          content:
            text/plain:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/GameNotFound'
                  - $ref: '#/components/schemas/SessionNotFound'
  /{game_id}/wait-for-update:
    get:
      tags:
        - Game
      summary: Wait for update
      description: >
        Receive a response when the clock exceeds the given value
        (defaulting to the current clock value) or the request times out
      operationId: waitForUpdate
      parameters:
        - in: path
          name: game_id
          schema:
            $ref: '#/components/schemas/GameId'
          required: true
          description: ID of a game
        - in: query
          name: since
          schema:
            type: integer
          description: >
            The clock value that must be exceeded for a non-timeout
            response (defaults to the current clock value)
          required: false
      responses:
        200:
          description: Clock exceeded `since` or request timed out
          content:
            application/json:
              schema:
                required:
                  - clock
                type: object
                properties:
                  clock:
                    type: integer
                    description: The current clock value at the server
        400:
          description: >
            Path or query deserialization error
          content:
            text/plain:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PathDeserializeError'
                  - $ref: '#/components/schemas/QueryDeserializeError'
components:
  schemas:
    GameTypeBase:
      type: string
      example: connect_4
      description: Type of game
    GameType:
      allOf:
        - $ref: '#/components/schemas/GameTypeBase'
        - enum:
            - connect_4
            - snake
    GameId:
      type: string
      example: game_NF6G5NI
      description: ID of a game
      pattern: game_[A-Z0-9]+
    SessionId:
      type: string
      example: session_AOHL56GENZPMVKFHA2LD5MOYRA
      description: ID of a session
      pattern: session_[A-Z0-9]+
    Username:
      type: string
      minLength: 1
      maxLength: 12
      example: Player 1
      description: Name of a player
    GameSummaryBase:
      type: object
      required:
        - players
        - stage
        - last_updated
      properties:
        players:
          type: array
          items:
            $ref: '#/components/schemas/Username'
          description: The usernames of players currently in the game
          example:
            - Player 1
            - Player 2
        stage:
          $ref: '#/components/schemas/Stage'
        last_updated:
          type: string
          format: date-time
          description: >
            The time of the most recent update to the game's state
          example: 2022-02-22T12:33:30+0000
    Stage:
      type: string
      enum:
        - waiting
        - in_progress
        - ended
      description: >
        Whether a game is waiting for players, in progress or
        over
      example: in_progress
    Connect4Request:
      type: object
      required:
        - game_type
        - cells
      properties:
        game_type:
          allOf:
            - $ref: '#/components/schemas/GameTypeBase'
            - enum: [ 'connect_4' ]
        cells:
          type: array
          items:
            type: array
            items:
              $ref: '#/components/schemas/Username'
            description: >
              A column from a connect 4 game, with tokens being
              represented by the usernames of the players who
              placed them and the bottom token being the
              leftmost
            maxItems: 6
          description: An array of a connect 4 game's columns
          minItems: 7
          maxItems: 7
          example:
            - [ ]
            - [ "Player 1", "Player 2" ]
            - [ "Player 2" ]
            - [ "Player 1" ]
            - [ ]
            - [ ]
            - [ ]
      description: Payload for a connect 4 game's state
    Connect4Response:
      type: object
      required:
        - game_type
        - column
      properties:
        game_type:
          allOf:
            - $ref: '#/components/schemas/GameTypeBase'
            - enum: [ 'connect_4' ]
        column:
          type: integer
          minimum: 1
          maximum: 7
      description: Payload for a connect 4 game move
    JSONDeserializeError:
      type: string
      pattern: '^Json deserialize error:'
    PathDeserializeError:
      type: string
      pattern: '^Path deserialize error:'
    QueryDeserializeError:
      type: string
      pattern: '^Query deserialize error:'
    Point2D:
      type: object
      required:
        - x
        - y
      properties:
        x:
          type: integer
          description: The x coordinate of this point
          example: 47
        y:
          type: integer
          description: The y coordinate of this point
          example: -38
    SnakeRequest:
      type: object
      required:
        - game_type
        - players
        - fruits
        - world_min
        - world_max
      properties:
        game_type:
          allOf:
            - $ref: '#/components/schemas/GameTypeBase'
            - enum: [ 'snake' ]
        players:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/Point2D'
            description: >
              The list of points occupied by a player. The first
              element in the list is the front of the snake.
            minItems: 1
          description: An map from players to arrays of occupied points.
          example:
            henry:
              - x: 3
                y: 4
              - x: 4
                y: 4
              - x: 5
                y: 4
        fruits:
          type: array
          items:
            $ref: '#/components/schemas/Point2D'
            description: >
              A list of 2D points representing the locations of
              fruit.
          example:
            - x: 7
              y: 14
            - x: -6
              y: 8
        world_min:
          $ref: '#/components/schemas/Point2D'
          description: The point in the world with minimum x and y values (inclusive)
        world_max:
          $ref: '#/components/schemas/Point2D'
          description: The point in the world with maximum x and y values (inclusive)
      description: Payload for a snake game's state
    SnakeResponse:
      type: object
      required:
        - game_type
        - direction
      properties:
        game_type:
          allOf:
            - $ref: '#/components/schemas/GameTypeBase'
            - enum: [ 'snake' ]
        direction:
          type: string
          enum:
            - up
            - down
            - left
            - right
      description: Payload for a snake game move
    PayloadSizeError:
      type: string
      pattern: '^Json payload size is bigger than allowed$'
      example: 'Json payload size is bigger than allowed'
    GameNotFound:
      type: string
      pattern: '^game game_[A-Z0-9]+ does not exist$'
      example: 'game game_NF6G5NI does not exist'
    SessionNotFound:
      type: string
      pattern: '^session session_[A-Z0-9]+ does not exist$'
      example: 'session session_AOHL56GENZPMVKFHA2LD5MOYRA does not exist'
    InvalidUsername:
      type: string
      pattern: '^invalid username \((already in game game_[A-Z0-9]+|too short|longer than 12 characters)\): .*$'
      example: 'invalid username (already in game): Player 1'
    GameWaiting:
      type: string
      pattern: '^game has not started yet (game_[A-Z0-9]+)$'
      example: 'game has not started yet (game_NF6G5NI)'
    GameInProgress:
      type: string
      pattern: '^game has already started (game_[A-Z0-9]+)$'
      example: 'game has already started (game_NF6G5NI)'
    GameEnded:
      type: string
      pattern: '^game game_[A-Z0-9]+ has already ended (game_[A-Z0-9]+)$'
      example: 'game has already ended (game_NF6G5NI)'
    InvalidMove:
      type: string
      pattern: '^invalid move: .* (game_[A-Z0-9]+)$'
      example: 'invalid move: column 3 is already full (game_NF6G5NI)'
    InvalidPlayer:
      type: string
      pattern: '^player .+ cannot move at the moment (game_[A-Z0-9]+)$'
      example: 'player Player 1 cannot move at the moment (game_NF6G5NI)'
  links:
    GameIdJoinGame:
      operationId: joinGame
      parameters:
        game_id: '$response.body#/game_id'
      description: >
        The `game_id` value returned in the response can be used as
        the `game_id` parameter in `POST /{game_id}/join-game`
    GameIdGetState:
      operationId: getState
      parameters:
        game_id: '$response.body#/game_id'
      description: >
        The `game_id` value returned in the response can be used as
        the `game_id` parameter in `GET /{game_id}/get-state`
    GameIdSubmitMove:
      operationId: submitMove
      parameters:
        game_id: '$response.body#/game_id'
      description: >
        The `game_id` value returned in the response can be used as
        the `game_id` parameter in `POST /{game_id}/submit-move/`
    SessionIdSubmitMove:
      operationId: submitMove
      x-apigraph-requestBodyParameters:
        /session_id: '$response.body#/session_id'
      description: >
        The `session_id` value returned in the response can be used as
        the `session_id` field in `POST /{game_id}/submit-move/`