server-api.yaml

openapi: 3.0.0
info:
  title: VM Management API
  description: API for managing VMs via REST endpoints.
  version: 2.0.0
servers:
  - url: http://{host}:{port}
    description: Development server
    variables:
      host:
        default: localhost
      port:
        default: "8080"
paths:
  /v1/health:
    get:
      summary: Health check endpoint
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "healthy"
                  timestamp:
                    type: string
                    format: date-time
                    example: "2023-05-26T07:17:03Z"
        '503':
          description: Service is unhealthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/vms:
    get:
      summary: List all VMs
      responses:
        '200':
          description: List of all VMs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAllVMsResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      summary: Start a VM
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartVMRequest'
      responses:
        '200':
          description: Successfully started VM
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartVMResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Destroy all VMs
      responses:
        '200':
          description: Successfully destroyed all VMs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DestroyAllVMsResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/vms/{name}:
    get:
      summary: Get details of a specific VM
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the VM
          schema:
            type: string
      responses:
        '200':
          description: VM details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListVMResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      summary: Update the state of a specific VM
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the VM
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum: [stopped, paused]
                  description: Action to perform on the VM
      responses:
        '200':
          description: Successfully updated VM state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VMResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: VM not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Destroy a specific VM
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the VM to destroy
          schema:
            type: string
      responses:
        '200':
          description: Successfully destroyed VM
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VMResponse'
        '404':
          description: VM not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/vms/{name}/snapshots:
    post:
      summary: Create a snapshot of a VM
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the VM to snapshot
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                snapshotId:
                  type: string
                  description: Unique identifier for the snapshot
      responses:
        '200':
          description: Successfully created snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VMSnapshotResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: VM not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/vms/{name}/cmd:
    post:
      summary: Execute command in VM
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the VM
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VmCommandRequest'
      responses:
        '200':
          description: Command executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VmCommandResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: VM not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/vms/{name}/files:
    post:
      summary: Upload files to VM
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the VM
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VmFileUploadRequest'
      responses:
        '200':
          description: Files uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VmFileUploadResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: VM not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      summary: Download files from VM
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the VM
          schema:
            type: string
        - name: paths
          in: query
          required: true
          description: Comma-separated list of file paths to download
          schema:
            type: string
      responses:
        '200':
          description: Files downloaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VmFileDownloadResponse'
        '400':
          description: Missing paths parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: VM not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Error message describing what went wrong
    StartVMRequest:
      type: object
      properties:
        vmName:
          type: string
          description: Name of the VM to start
        kernel:
          type: string
          description: Path of the kernel image to be used
        initramfs:
          type: string
          description: Path of the initramfs image to be used
        rootfs:
          type: string
          description: Path of the rootfs image to be used
        entryPoint:
          type: string
          description: Optional entry point to start in the VM upon boot
        snapshotId:
          type: string
          description: Optional ID of the snapshot to restore from. If provided, kernel and rootfs are ignored
    StartVMResponse:
      type: object
      properties:
        vmName:
          type: string
        status:
          type: string
        ip:
          type: string
        tapDeviceName:
          type: string
        portForwards:
          type: array
          items:
            $ref: '#/components/schemas/PortForward'
    VMRequest:
      type: object
      properties:
        vmName:
          type: string
          description: Name of the VM
    VMResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
    DestroyAllVMsResponse:
      type: object
      properties:
        success:
          type: boolean
    ListAllVMsResponse:
      type: object
      properties:
        vms:
          type: array
          items:
            type: object
            properties:
              vmName:
                type: string
              status:
                type: string
              ip:
                type: string
              tapDeviceName:
                type: string
              portForwards:
                type: array
                items:
                  $ref: '#/components/schemas/PortForward'
    ListVMResponse:
      type: object
      properties:
        vmName:
          type: string
        status:
          type: string
        ip:
          type: string
        tapDeviceName:
          type: string
        portForwards:
          type: array
          items:
            $ref: '#/components/schemas/PortForward'
    VmCommandRequest:
      type: object
      required:
        - cmd
      properties:
        cmd:
          type: string
          description: Command to execute in the VM
        blocking:
          type: boolean
          description: Whether to wait for the command to complete before returning (default true)
    VmCommandResponse:
      type: object
      properties:
        output:
          type: string
          description: Command output
        error:
          type: string
          description: Error message if command failed
    VmFileUploadRequest:
      type: object
      required:
        - files
      properties:
        files:
          type: array
          description: Files to upload to the VM
          items:
            type: object
            required:
              - path
              - content
            properties:
              path:
                type: string
                description: Path where to save the file in the VM
              content:
                type: string
                description: Content of the file
    VmFileUploadResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message if file upload failed
    VmFileDownloadResponse:
      type: object
      properties:
        files:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
                description: Path of the file
              content:
                type: string
                description: Content of the file
              error:
                type: string
                description: Error message if file download failed
    PortForward:
      type: object
      properties:
        hostPort:
          type: string
        guestPort:
          type: string
        description:
          type: string
          description: Description of what's running on this port
    VMSnapshotResponse:
      type: object
      properties:
        snapshotId:
          type: string