openapi: 3.0.0
info:
  title: Albatross internal web API
  version: 0.1.0
paths:
  /login:
    post:
      operationId: postLogin
      summary: User login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  example: "john"
                password:
                  type: string
                  example: "password123"
              required:
                - username
                - password
      responses:
        '200':
          description: Successfully authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    example: "xxxxx.xxxxx.xxxxx"
                required:
                  - token
        '401':
          $ref: '#/components/responses/Unauthorized'
  /games:
    get:
      operationId: getGames
      summary: List games
      parameters:
        - $ref: '#/components/parameters/header_authorization'
      responses:
        '200':
          description: List of games
          content:
            application/json:
              schema:
                type: object
                properties:
                  games:
                    type: array
                    items:
                      $ref: '#/components/schemas/Game'
                required:
                  - games
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /games/{game_id}:
    get:
      operationId: getGame
      summary: Get a game
      parameters:
        - $ref: '#/components/parameters/header_authorization'
        - $ref: '#/components/parameters/path_game_id'
      responses:
        '200':
          description: A game
          content:
            application/json:
              schema:
                type: object
                properties:
                  game:
                    $ref: '#/components/schemas/Game'
                required:
                  - game
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /games/{game_id}/play/latest_state:
    get:
      operationId: getGamePlayLatestState
      summary: Get the latest execution result for player
      parameters:
        - $ref: '#/components/parameters/header_authorization'
        - $ref: '#/components/parameters/path_game_id'
      responses:
        '200':
          description: Your latest game state
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    $ref: '#/components/schemas/LatestGameState'
                required:
                  - state
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /games/{game_id}/play/code:
    post:
      operationId: postGamePlayCode
      summary: Post the latest code
      parameters:
        - $ref: '#/components/parameters/header_authorization'
        - $ref: '#/components/parameters/path_game_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  example: "echo 'hello world';"
              required:
                - code
      responses:
        '200':
          description: Successfully updated
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /games/{game_id}/play/submit:
    post:
      operationId: postGamePlaySubmit
      summary: Submit the answer
      parameters:
        - $ref: '#/components/parameters/header_authorization'
        - $ref: '#/components/parameters/path_game_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  example: "echo 'hello world';"
              required:
                - code
      responses:
        '200':
          description: Successfully submitted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /games/{game_id}/watch/ranking:
    get:
      operationId: getGameWatchRanking
      summary: Get the latest player ranking
      parameters:
        - $ref: '#/components/parameters/header_authorization'
        - $ref: '#/components/parameters/path_game_id'
      responses:
        '200':
          description: Player ranking
          content:
            application/json:
              schema:
                type: object
                properties:
                  ranking:
                    type: array
                    items:
                      $ref: '#/components/schemas/RankingEntry'
                required:
                  - ranking
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /games/{game_id}/watch/latest_states:
    get:
      operationId: getGameWatchLatestStates
      summary: Get all the latest game states of the main players
      parameters:
        - $ref: '#/components/parameters/header_authorization'
        - $ref: '#/components/parameters/path_game_id'
      responses:
        '200':
          description: All the latest game states of the main players
          content:
            application/json:
              schema:
                type: object
                properties:
                  states:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/LatestGameState'
                required:
                  - states
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    header_authorization:
      in: header
      name: Authorization
      schema:
        type: string
      required: true
    path_game_id:
      in: path
      name: game_id
      schema:
        type: integer
      required: true
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
          example: "Invalid request"
      required:
        - message
    User:
      type: object
      properties:
        user_id:
          type: integer
          example: 123
        username:
          type: string
          example: "john"
        display_name:
          type: string
          example: "John Doe"
        icon_path:
          type: string
          example: "/images/john.jpg"
        is_admin:
          type: boolean
          example: false
        label:
          type: string
          nullable: true
          example: "staff"
      required:
        - user_id
        - username
        - display_name
        - is_admin
        - label
    Game:
      type: object
      properties:
        game_id:
          type: integer
          example: 1
        game_type:
          type: string
          example: "1v1"
          enum:
            - 1v1
            - multiplayer
        is_public:
          type: boolean
          example: true
        display_name:
          type: string
          example: "Game 1"
        duration_seconds:
          type: integer
          example: 360
        started_at:
          type: integer
          example: 946684800
          x-go-type: int64
        problem:
          $ref: '#/components/schemas/Problem'
        main_players:
          type: array
          items:
            $ref: '#/components/schemas/User'
      required:
        - game_id
        - game_type
        - is_public
        - display_name
        - duration_seconds
        - problem
        - main_players
    Problem:
      type: object
      properties:
        problem_id:
          type: integer
          example: 1
        title:
          type: string
          example: "Problem 1"
        description:
          type: string
          example: "This is a problem"
        sample_code:
          type: string
          example: "echo 'hello world';"
      required:
        - problem_id
        - title
        - description
        - sample_code
    ExecutionStatus:
      type: string
      example: "success"
      enum:
        - none
        - running
        - success
        - wrong_answer
        - timeout
        - runtime_error
        - internal_error
    LatestGameState:
      type: object
      properties:
        code:
          type: string
          example: "echo 'hello world';"
        score:
          type: integer
          nullable: true
          example: 100
        best_score_submitted_at:
          type: integer
          nullable: true
          example: 946684800
          x-go-type: int64
        status:
          $ref: '#/components/schemas/ExecutionStatus'
      required:
        - code
        - score
        - best_score_submitted_at
        - status
    RankingEntry:
      type: object
      properties:
        player:
          $ref: '#/components/schemas/User'
        score:
          type: integer
          example: 100
        submitted_at:
          type: integer
          example: 946684800
          x-go-type: int64
      required:
        - player
        - score
        - submitted_at