openapi: 3.0.0
info:
  version: 1.0.0
  title: Devbook
  description: Devbook API

servers:
  - url: https://ondevbook.com/
    description: API endpoint
  - url: https://{sessionID}-{clientID}.ondevbook.com/
    description: Session endpoint without a specified port
    variables:
      sessionID:
        description: ID of the session
        default: _sessionID
      clientID:
        description: ID of the client
        default: _clientID
  - url: https://{port}-{sessionID}-{clientID}.ondevbook.com/
    description: Session endpoint with a specificed port
    variables:
      sessionID:
        description: ID of the session
        default: _sessionID
      clientID:
        description: ID of the client
        default: _clientID
      port:
        description: Devbook Daemon default port
        default: "49982"

components:
  securitySchemes:
    ApiKeyAuth:
      name: api_key
      type: apiKey
      in: query

  parameters:
    apiKeyOpt:
      name: api_key
      in: query
      required: false
      schema:
        type: string
    apiKeyReq:
      name: api_key
      in: query
      required: true
      schema:
        type: string
    codeSnippetID:
      name: codeSnippetID
      in: path
      required: true
      schema:
        type: string
    sessionID:
      name: sessionID
      in: path
      required: true
      schema:
        type: string

  responses:
    400:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    401:
      description: Authentication error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    500:
      description: Server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  schemas:
    Template:
      type: string
      enum:
        - Nodejs
        - Go
        - Bash
        - Rust
        - Python3
        - PHP
        - Java
        - Perl
        - DotNET

    EnvironmentState:
      type: string
      enum:
        - Building
        - Failed
        - Done

    Environment:
      required:
        - id
      properties:
        id:
          type: string
        template:
          type: string
        title:
          type: string

    NewEnvironment:
      required:
        - template
      properties:
        title:
          type: string
        template:
          type: string

    EnvironmentStateUpdate:
      required:
        - state
      properties:
        state:
          $ref: "#/components/schemas/EnvironmentState"

    EnvironmentTitleUpdate:
      properties:
        title:
          type: string

    NewSession:
      required:
        - codeSnippetID
      properties:
        editEnabled:
          type: boolean
          default: false
          description: Option determining if the session is a shared persistent edit session
        codeSnippetID:
          type: string
          description: Identifier of a code snippet which which is the environment associated
    Session:
      required:
        - sessionID
        - clientID
        - editEnabled
        - codeSnippetID
      properties:
        codeSnippetID:
          type: string
          description: Identifier of a code snippet which which is the environment associated
        editEnabled:
          type: boolean
          description: Information if the session is a shared persistent edit session
        sessionID:
          type: string
          description: Identifier of the session
        clientID:
          type: string
          description: Identifier of the client

    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          description: Error code
        message:
          type: string
          description: Error

tags:
  - name: sessions
    description: Managing VM sessions
  - name: envs
    description: Environment for VM

paths:
  /health:
    get:
      description: Health check
      responses:
        200:
          description: Request was successful
        401:
          $ref: "#/components/responses/401"

  /sessions:
    get:
      description: List all sessions
      tags: [ sessions ]
      parameters:
        - $ref: "#/components/parameters/apiKeyReq"
      responses:
        200:
          description: Successfully returned all sessions
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: "#/components/schemas/Session"
        401:
          $ref: "#/components/responses/401"
        500:
          $ref: "#/components/responses/500"
    post:
      description: Create a session on the server
      tags: [ sessions ]
      parameters:
        - $ref: "#/components/parameters/apiKeyOpt"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewSession"
      responses:
        201:
          description: Successfully created a session
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Session"
        401:
          $ref: "#/components/responses/401"
        400:
          $ref: "#/components/responses/400"
        500:
          $ref: "#/components/responses/500"

  /sessions/{sessionID}:
    delete:
      description: Delete a session on the server
      tags: [ sessions ]
      parameters:
        - $ref: "#/components/parameters/apiKeyReq"
        - $ref: "#/components/parameters/sessionID"
      responses:
        204:
          description: Successfully deleted the session
        401:
          $ref: "#/components/responses/401"
        500:
          $ref: "#/components/responses/500"

  /sessions/{sessionID}/refresh:
    post:
      description: Refresh the session extending its time to live
      tags: [ sessions ]
      parameters:
        - $ref: "#/components/parameters/apiKeyOpt"
        - $ref: "#/components/parameters/sessionID"
      responses:
        204:
          description: Successfully refreshed the session
        401:
          $ref: "#/components/responses/401"
        404:
          description: Error refreshing session - session not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /envs:
    get:
      description: List all environments
      tags: [ envs ]
      parameters:
        - $ref: "#/components/parameters/apiKeyReq"
      responses:
        200:
          description: Successfully returned all environments
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: "#/components/schemas/Environment"
        401:
          $ref: "#/components/responses/401"
        500:
          $ref: "#/components/responses/500"
    post:
      description: Create a new environment
      tags: [ envs ]
      parameters:
        - $ref: "#/components/parameters/apiKeyReq"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewEnvironment"
      responses:
        200:
          description: Successfully created an environment
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Environment"
        400:
          $ref: "#/components/responses/400"
        401:
          $ref: "#/components/responses/401"
        500:
          $ref: "#/components/responses/500"

  # This method will be replaced by POST /envs
  /envs/{codeSnippetID}:
    post:
      description: Create a new env for a code snippet
      tags: [ envs ]
      parameters:
        - $ref: "#/components/parameters/apiKeyReq"
        - $ref: "#/components/parameters/codeSnippetID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewEnvironment"
      responses:
        204:
          description: Successfully created an environment
        400:
          $ref: "#/components/responses/400"
        401:
          $ref: "#/components/responses/401"
        500:
          $ref: "#/components/responses/500"
    delete:
      description: Delete the code snippet environment
      tags: [ envs ]
      parameters:
        - $ref: "#/components/parameters/apiKeyReq"
        - $ref: "#/components/parameters/codeSnippetID"
      responses:
        204:
          description: Successfully deleted the environment
        400:
          description: Cannot delete the environment
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          $ref: "#/components/responses/401"
        500:
          $ref: "#/components/responses/500"
    patch:
      description: Update the environment of the code snippet to match the edit environment
      tags: [ envs ]
      parameters:
        - $ref: "#/components/parameters/apiKeyReq"
        - $ref: "#/components/parameters/codeSnippetID"
      responses:
        204:
          description: Updated the edit environment for code snippet
        400:
          $ref: "#/components/responses/400"
        401:
          $ref: "#/components/responses/401"
        500:
          $ref: "#/components/responses/500"

  /envs/{codeSnippetID}/state:
    put:
      description: Update the state of the environment
      tags: [ envs ]
      parameters:
        - $ref: "#/components/parameters/apiKeyReq"
        - $ref: "#/components/parameters/codeSnippetID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EnvironmentStateUpdate"
      responses:
        204:
          description: Updated the state of environment
        400:
          $ref: "#/components/responses/400"
        401:
          $ref: "#/components/responses/401"

  /envs/{codeSnippetID}/title:
    put:
      description: Update the title of the environment
      tags: [ envs ]
      parameters:
        - $ref: "#/components/parameters/apiKeyReq"
        - $ref: "#/components/parameters/codeSnippetID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EnvironmentTitleUpdate"
      responses:
        204:
          description: Updated the title of the code snippet
        400:
          $ref: "#/components/responses/400"
        401:
          $ref: "#/components/responses/401"