openapi: 3.1.0
info:
  title: Digital Extinction lobby server API
  version: 0.1.0-dev

paths:
  /p/auth/sign-up:
    post:
      summary: Create a new user registration.
      description: This endpoint creates a new user registration.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  type: string
                  description: >-
                    A Unicode string with length between 6 and 30 bytes when
                    encoded in UTF-8.
                user:
                  $ref: "#/components/schemas/user"
      responses:
        "200":
          description: Registration was successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/token-response"
        "409":
          description: >-
            Registration was not successful because the username is already
            taken.

  /p/auth/sign-in:
    post:
      summary: Retrieve a fresh JWT.
      description: >-
        This endpoint is used to retrieve a fresh JWT to be used for
        authentication to other API endpoints.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                password:
                  type: string

      responses:
        "200":
          description: The username exists and the password is correct.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/token-response"
        "401":
          description: >-
            The username does not exist or the password is not correct.
  /a/games:
    get:
      summary: List games.
      description: This endpoint returns list of all games on the server.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Game listing.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    numPlayers:
                      type: integer
                      description: >-
                        Number of players who already joined the game.
                      minimum: 1
                    config:
                      $ref: "#/components/schemas/game-config"
    post:
      summary: Create and join a new game.
      description: >-
        This endpoint is used to crate a new game. The user automatically joins
        the game. It is not possible to simultaneously be part of multiple
        games.
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/game-setup"
      responses:
        "200":
          description: The game was successfully crated and the user joined it.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/empty"
        "400":
          description: >-
            The game cannot be created because the request is invalid. This
            might be due to invalid game configuration.
        "403":
          description: The user is already part of another game.
        "409":
          description: A different game with the same name already exists.

  /a/games/{name}:
    get:
      summary: Get complete information about a game.
      security:
        - bearerAuth: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Game successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  players:
                    type: array
                    items:
                      type: object
                      properties:
                        username:
                          type: string
                        info:
                          type: object
                          properties:
                            ordinal:
                              type: number
                  setup:
                    $ref: "#/components/schemas/game-setup"
        "404":
          description: The game does not exist.

  /a/games/{name}/join:
    put:
      summary: Join the game.
      description: >-
        Join the game. The client must not be part of another game (including
        this one).
      security:
        - bearerAuth: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ordinal:
                  type: integer
                  minimum: 1
                  description: >-
                    Each player of the game has a unique number in the range
                    from 1 to N, where N is the maximum allowed number of
                    players in the game. This parameter sets the number for the
                    joining player.
      responses:
        "200":
          description: The user successfully joined the game.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/empty"
        "403":
          description: The user is already part of a game.
        "404":
          description: The game does not exist.
        "409":
          description: >-
            The ordinal is too large or another player with the same ordinal
            has already joined the game.

  /a/games/{name}/leave:
    put:
      summary: Leave or abandon a game.
      description: >-
        Leave the game. The client needs to be part of the game. The game is
        abandoned / canceled when the author leaves the game.
      security:
        - bearerAuth: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The user successfully left the game.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/empty"
        "403":
          description: The user is not part of the game.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    empty:
      type: object
      properties: {}
    token-response:
      type: object
      properties:
        token:
          type: string
          description: >-
            A JWT token. The user uses the token to authenticate to the API.
    user:
      type: object
      properties:
        username:
          type: string
          description: >-
            A unique user name. It is a non-empty Unicode string with maximum
            length of 32 bytes when encoded in UTF-8. It does not start or end
            with whitespace.
    game-setup:
      type: object
      properties:
        server:
          type: string
          description: >-
            An IPv4 or IPv6 socket address. For example 127.0.0.1:8082.
        config:
          $ref: "#/components/schemas/game-config"

    game-config:
      type: object
      properties:
        name:
          type: string
          description: A unique game name.
        maxPlayers:
          type: integer
          minimum: 2
          maximum: 4
        map:
          type: object
          properties:
            hash:
              type: string
              description: >-
                Map hash used for precise map identification. It is a 64
                character long hex string.
            name:
              type: string
              description: Name of the game map.