openapi.yaml

openapi: "3.0.3"
info:
  title: Database Playground Gateway API
  description: The RESTful API of the Database Playground Gateway
  version: "1.0.0"
servers:
  - url: http://localhost:3100
    description: Development server
paths:
  /healthz:
    get:
      summary: Check the health of the gateway
      tags: [Health]
      responses:
        "200":
          description: The gateway is healthy
  /questions:
    get:
      summary: List all questions
      tags: [Questions]
      security:
        - logto-jwt-token: ["read:question"]
      parameters:
        - in: query
          name: limit
          schema:
            type: number
            x-go-type: int64
          description: The number of items to return
        - in: query
          name: offset
          schema:
            type: number
            x-go-type: int64
          description: The number of items to skip before starting to collect the result set
      responses:
        "200":
          description: A list of questions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Questions"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "500":
          $ref: "#/components/responses/Error"
  /questions/{id}:
    get:
      summary: Get a question by ID
      tags: [Questions]
      security:
        - logto-jwt-token: ["read:question"]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the question to retrieve
      responses:
        "200":
          description: A question
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Question"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/NoSuchResourceError"
        "500":
          $ref: "#/components/responses/Error"
  /questions/{id}/solution:
    get:
      summary: Get the solution of a question by ID
      description: |
        Note that when calling this method, it consumes
        the experience points of the user (by 20).
      tags: [Questions]
      security:
        - logto-jwt-token: ["read:solution"]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the question to retrieve the solution of
      responses:
        "200":
          description: The solution of the question
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuestionSolution"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/NoSuchResourceError"
        "500":
          $ref: "#/components/responses/Error"
  /challenges:
    post:
      summary: Create an challenge of a question.
      description: |
        The challenge is an asynchronous operation that will return the challenge ID to the client. The client can then use the challenge ID to query the result of the challenge or compare the result with the answer.

        Note that the challenge will be available for 1 hour, and your challenge result will be cached. Therefore, if you want to re-execute the challenge without worrying about the token expiring, you can simply create a new challenge, and there will be no additional cost.
      security:
        - logto-jwt-token: ["challenge"]
      tags: [Challenges]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                questionID:
                  type: string
                query:
                  type: string
              required:
                - questionID
                - query
      responses:
        "200":
          description: The result of the query
          content:
            application/json:
              schema:
                type: object
                properties:
                  challengeID:
                    type: string
                required:
                  - challengeID
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "422":
          $ref: "#/components/responses/UnprocessableEntityError"
        "404":
          $ref: "#/components/responses/NoSuchResourceError"
        "500":
          $ref: "#/components/responses/Error"
  /challenges/{id}:
    get:
      summary: Get the result of a challenge by ID
      tags: [Challenges]
      security:
        - logto-jwt-token: ["challenge"]
      parameters:
        - in: path
          required: true
          name: id
          schema:
            type: string
          description: The ID of the challenge to retrieve the result of
      responses:
        "200":
          description: The result of the challenge
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueryResult"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/NoSuchResourceError"
        "500":
          $ref: "#/components/responses/Error"
  /challenges/{id}/compare:
    get:
      summary: Compare the result of a challenge with the answer
      tags: [Challenges]
      security:
        - logto-jwt-token: ["challenge", "read:question"]
      parameters:
        - in: path
          required: true
          name: id
          schema:
            type: string
          description: The ID of the challenge to compare the result of
      responses:
        "200":
          description: The result of the comparison
          content:
            application/json:
              schema:
                type: object
                properties:
                  same:
                    type: boolean
                required:
                  - same
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/NoSuchResourceError"
        "500":
          $ref: "#/components/responses/Error"
  /schemas/{id}:
    get:
      summary: Get a schema by ID
      tags: [Schemas]
      security:
        - logto-jwt-token: ["read:schema"]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the schema to retrieve
      responses:
        "200":
          description: A schema
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Schema"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/NoSuchResourceError"
        "500":
          $ref: "#/components/responses/Error"
components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
      required:
        - message
    Questions:
      type: array
      items:
        $ref: "#/components/schemas/Question"
    Question:
      type: object
      properties:
        id:
          type: string
        schema_id:
          type: string
        type:
          type: string
        difficulty:
          type: string
          enum: ["", easy, medium, hard]
        title:
          type: string
        description:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - schema_id
        - type
        - difficulty
        - title
        - description
        - created_at
        - updated_at
    QuestionAnswer:
      type: object
      properties:
        id:
          type: string
        answer:
          type: string
      required:
        - id
        - answer
    QuestionSolution:
      type: object
      properties:
        id:
          type: string
        solution_video:
          type: string
          nullable: true
          example: "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
      required:
        - id
        - solution_video
    Schema:
      type: object
      properties:
        id:
          type: string
        picture:
          type: string
          nullable: true
        description:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - description
        - created_at
        - updated_at
    SchemaInitialSQL:
      type: object
      properties:
        id:
          type: string
        initial_sql:
          type: string
      required:
        - id
        - initial_sql
    QueryResult:
      type: object
      properties:
        header:
          type: array
          items:
            type: string
        rows:
          type: array
          items:
            type: array
            items:
              type: string
              nullable: true
              x-go-type: "*string"
      required:
        - header
        - rows
  responses:
    UnauthorizedError:
      description: The request has not been applied because it lacks valid authentication credentials for the target resource.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NoSuchResourceError:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    BadRequestError:
      description: The provided request is invalid.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    UnprocessableEntityError:
      description: The provided request is valid, but the server is unable to process it.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Error:
      description: A generic error message.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  securitySchemes:
    logto-jwt-token:
      type: http
      scheme: bearer
      bearerFormat: JWT