lambda-api.yaml

openapi: 3.1.0
info:
  title: lambda-api
  version: "0.1"
  description: Lambda-based API for manipulating labs/tasks and running tests
  license:
    name: Apache 2.0
    identifier: Apache-2.0
servers:
  - url: "http://localhost:3000"
paths:
  /labs:
    get:
      summary: Get Labs
      tags:
        - Public
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: Unique id of a lab
                    data:
                      $ref: "#/components/schemas/Lab"
                  required:
                    - id
                    - data
      operationId: get-labs
      description: Get list of created labs' descriptions
      parameters: []
    parameters: []
    post:
      summary: Create Lab
      operationId: create-lab
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: string
                description: ID of created lab
                readOnly: true
        "400":
          $ref: "#/components/responses/Bad-Request-Data"
        "401":
          $ref: "#/components/responses/Unauthorized-Admin-Request"
      description: Create new lab by description
      tags:
        - Admin
      parameters:
        - $ref: "#/components/parameters/Admin-Auth"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Lab"
        description: New lab description
  "/lab/{labid}":
    parameters:
      - $ref: "#/components/parameters/Lab-Id"
    delete:
      summary: Delete lab
      operationId: delete-lab
      responses:
        "200":
          description: OK
        "401":
          $ref: "#/components/responses/Unauthorized-Admin-Request"
        "404":
          $ref: "#/components/responses/Resource-Not-Found"
      description: Delete lab with given id
      parameters:
        - $ref: "#/components/parameters/Admin-Auth"
      tags:
        - Admin
  "/lab/{labid}/tasks":
    parameters:
      - $ref: "#/components/parameters/Lab-Id"
    get:
      summary: Get lab tasks
      tags:
        - Public
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: Unique id of task
                    data:
                      $ref: "#/components/schemas/Task"
                  required:
                    - id
                    - data
        "404":
          $ref: "#/components/responses/Resource-Not-Found"
      operationId: get-lab-tasks
      description: Get tasks' descriptions for lab
    post:
      summary: Create lab task
      operationId: create-lab-task
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: string
                description: ID of created task
                readOnly: true
        "400":
          $ref: "#/components/responses/Bad-Request-Data"
        "401":
          $ref: "#/components/responses/Unauthorized-Admin-Request"
        "404":
          $ref: "#/components/responses/Resource-Not-Found"
      description: Create a new task for the specified lab using the new task's description
      parameters:
        - $ref: "#/components/parameters/Admin-Auth"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Task"
        description: New task description
      tags:
        - Admin
  "/lab/{labid}/task/{taskid}":
    parameters:
      - $ref: "#/components/parameters/Lab-Id"
      - $ref: "#/components/parameters/Task-Id"
    post:
      summary: Add task data
      operationId: add-task-data
      responses:
        "200":
          description: OK
        "400":
          $ref: "#/components/responses/Bad-Request-Data"
        "401":
          $ref: "#/components/responses/Unauthorized-Admin-Request"
        "404":
          $ref: "#/components/responses/Resource-Not-Found"
      parameters:
        - $ref: "#/components/parameters/Admin-Auth"
      description: "Links additional information to task. Currently only files (generator, validator)"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: Type of file linked (generator/validator)
                  enum:
                    - generator
                    - validator
                file:
                  $ref: "#/components/schemas/CodeFile"
              required:
                - type
            examples: {}
        description: Linked file data
      tags:
        - Admin
    delete:
      summary: Delete task
      operationId: delete-task
      responses:
        "200":
          description: OK
        "401":
          $ref: "#/components/responses/Unauthorized-Admin-Request"
        "404":
          $ref: "#/components/responses/Resource-Not-Found"
      description: Deletes task inside lab with given ids
      parameters:
        - $ref: "#/components/parameters/Admin-Auth"
      tags:
        - Admin
  "/lab/{labid}/task/{taskid}/test":
    parameters:
      - schema:
          type: string
        name: labid
        in: path
        required: true
      - schema:
          type: string
        name: taskid
        in: path
        required: true
    post:
      summary: Run task test
      operationId: run-task-test
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: string
                description: "ID of the test run, which can be used to query the results of the run"
        "400":
          $ref: "#/components/responses/Bad-Request-Data"
        "404":
          $ref: "#/components/responses/Resource-Not-Found"
      description: Runs task tests with passed solution
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CodeFile"
      tags:
        - Public
    get:
      summary: Poll task test result
      operationId: poll-task-test
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Current status of test run
                    enum:
                      - QUEUE
                      - RUNNING
                      - DONE
                  tests:
                    type: array
                    description: Results of each test
                    items:
                      $ref: "#/components/schemas/TestResult"
                required:
                  - status
                  - tests
        "404":
          $ref: "#/components/responses/Resource-Not-Found"
      description: Poll test run results
      parameters:
        - schema:
            type: string
          in: query
          name: id
          required: true
          description: "ID of the test run, as given by POST"
      tags:
        - Public
components:
  schemas:
    Lab:
      title: Lab
      type: object
      examples:
        - name: Sem 3 Lab 1. DFS + MST
      description: General information about a lab
      properties:
        name:
          type: string
          description: Name of the lab like on Codeforces/PCMS
      required:
        - name
    Error:
      title: Error
      type: object
      properties:
        message:
          type: string
      required:
        - message
      examples:
        - message: Unauthorized request
      description: Error type which is returned on a failed request
    Task:
      title: Task
      type: object
      description: Information about a single task of a lab
      examples:
        - name: C. Vertice-Biconnected Components
      properties:
        name:
          type: string
          description: Name of task in this lab
      required:
        - name
    CodeFile:
      title: CodeFile
      type: object
      properties:
        lang:
          type: string
          description: Language of the data
        data:
          type: string
          description: Actual data of the file
      required:
        - lang
        - data
      description: One file of code written in some language
      examples:
        - lang: G++
          data: "int main(){ return 0; }"
    TestResult:
      title: TestResult
      type: object
      description: Results of a single test
      properties:
        result:
          type: string
          description: PASS/FAIL etc
          enum:
            - PASS
            - FAIL
            - ML
            - RE
            - CE
        message:
          type: string
          description: Description of result if result isn't OK/FAIl
        data:
          type: object
          properties:
            test:
              type: string
              description: "Test data, any format as given by task description"
            expected:
              type: string
              description: Answer given by the validator
            got:
              type: string
              description: Your answer
      required:
        - result
  securitySchemes: {}
  parameters:
    Admin-Auth:
      name: Authorization
      in: header
      schema:
        type: string
      required: true
      description: Basic Base64 encoded admin token
    Lab-Id:
      name: labid
      in: path
      required: true
      schema:
        type: string
        example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
      description: Unique ID of the lab as returned by GET /labs
    Task-Id:
      name: taskid
      in: path
      required: true
      schema:
        type: string
        example: "1"
      description: "Unique task id as returned by GET /lab/{labid}/tasks"
  responses:
    Unauthorized-Admin-Request:
      description: Unauthorized resource manipulation
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Resource-Not-Found:
      description: Resource queried by id wasn't found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Bad-Request-Data:
      description: "Invalid data sent in the request (unsupported, required fields missing etc)"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  requestBodies: {}
tags:
  - name: Admin
  - name: Public