openapi: 3.0.3

info:
  title: "Distributed Arcade"
  description: |-
    A super-fast high score gatherer using Rust and Redis.
  version: 0.1.0

servers:
  - url: "http://127.0.0.1:30000"

tags:
  - name: "Home"
    description: "Miscellaneous routes"
  - name: "Board"
    description: "About boards"
  - name: "Score"
    description: "Submit scores"

paths:
  /:
    get:
      summary: "Verify that the web server is working as expected"
      tags: ["Home"]
      responses:
        200:
          description: "Working as expected"
          content:
            application/json:
              schema:
                nullable: true
                example: null
    patch:
      summary: "Verify that everything is working as expected"
      tags: ["Home"]
      responses:
        200:
          description: "Working as expected"
          content:
            application/json:
              schema:
                nullable: true
                example: null
        500:
          description: "Did not receive `PONG` from redis"
          content:
            application/json:
              schema:
                type: string
                example: "Redis gave an unexpected response"
        502:
          $ref: "#/components/responses/RedisCmdFailed"
        504:
          $ref: "#/components/responses/RedisConnFailed"

  /board/:
    get:
      summary: "Get the scores of a board"
      tags: ["Board"]
      parameters:
        - $ref: "#/components/parameters/board"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/size"
      responses:
        200:
          description: "Scores retrieved successfully"
          content:
            application/json:
              schema:
                type: object
                properties:
                  offset:
                    type: integer
                    description: "The offset to pass to get the next page, or 0 if there are no more results."
                    example: 1
                  scores:
                    type: array
                    items:
                      type: object
                      description: "A score submitted by an user."
                      properties:
                        name:
                          type: string
                          description: "The name of the user who submitted the score."
                          example: "Steffo"
                        score:
                          type: number
                          description: "The submitted score."
                          example: 1234.56
        502:
          $ref: "#/components/responses/RedisCmdFailed"
        504:
          $ref: "#/components/responses/RedisConnFailed"

    post:
      summary: "Create a new board"
      tags: ["Board"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: "The name of the board to create."
                  example: "gravityfusion"
                order:
                  type: string
                  example: "DSC"
                  description: "The ordering of the board, either ascending or descending."
                  enum:
                    - "ASC"
                    - "DSC"
      responses:
        201:
          description: "Board created successfully"
          content:
            application/json:
              schema:
                type: string
                example: "W4SbhbJ3tnGaIM1S"
        409:
          description: "Board already exists"
          content:
            application/json:
              schema:
                type: string
                example: "Board already exists"
        500:
          description: "Could not generate secure board token"
          content:
            application/json:
              schema:
                type: string
                example: "Could not generate secure board token"
        502:
          $ref: "#/components/responses/RedisCmdFailed"
        504:
          $ref: "#/components/responses/RedisConnFailed"

  /score/:
    get:
      summary: "Get a score from a board"
      tags: ["Score"]
      parameters:
        - $ref: "#/components/parameters/board"
        - $ref: "#/components/parameters/player"
      responses:
        200:
          description: "Score retrieved successfully"
          content:
            application/json:
              schema:
                type: number
                description: "The score of the specified player."
                example: 1234.56
        502:
          $ref: "#/components/responses/RedisCmdFailed"
        504:
          $ref: "#/components/responses/RedisConnFailed"

    put:
      summary: "Submit a score to a board"
      tags: ["Score"]
      parameters:
        - $ref: "#/components/parameters/board"
        - $ref: "#/components/parameters/player"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: number
              description: "The score to submit to the board."
              example: 1234.56
      security:
        - XBoardToken: []
      responses:
        200:
          description: "Score discarded as it was worse than the previous one"
          content:
            application/json:
              schema:
                type: number
                description: "The previous score."
                example: 2468.12
        201:
          description: "Score submitted and updated"
          content:
            application/json:
              schema:
                type: number
                description: "The new score."
                example: 1234.56
        401:
          description: "Missing, invalid or malformed Authorization header"
          content:
            application/json:
              schema:
                type: string
                example: "Missing Authorization header"
        502:
          $ref: "#/components/responses/RedisCmdFailed"
        504:
          $ref: "#/components/responses/RedisConnFailed"


components:
  securitySchemes:
    XBoardToken:
      type: apiKey
      in: header
      name: "Authorization"

  parameters:
    board:
      name: "board"
      description: "The name of the board to operate on."
      in: query
      schema:
        type: string
    player:
      name: "player"
      description: "The name of the player to operate on."
      in: query
      schema:
        type: string
    offset:
      name: "offset"
      description: "The offset to start returning results from."
      in: query
      schema:
        type: integer
    size:
      name: "size"
      description: "How many results to return."
      in: query
      schema:
        type: integer
        minimum: 0
        maximum: 500

  responses:
    RedisCmdFailed:
      description: "Could not execute Redis command"
      content:
        application/json:
          schema:
            type: string
            example: "Could not execute Redis command"
    RedisConnFailed:
      description: "Could not connect to Redis"
      content:
        application/json:
          schema:
            type: string
            example: "Could not connect to Redis"