openapi.yaml

openapi: "3.0.1"

info:
  title: Janna API docs
  description: "Janna provides a REST API interface for some ESXi/vSphere functions"
  version: 'v0.6.0'
  license:
    name: "MIT"
    url: http://opensource.org/licenses/MIT

servers:
- url: http://localhost:8080/
  description: localhost server

paths:
  /info:
    get:
      summary: "Information about the Janna build"
      tags:
      - Service state
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/build_info_response"


  /healthz:
    get:
      summary: "Liveness probe"
      tags:
      - Service state
      responses:
        '200':
          description: OK

  /readyz:
    get:
      summary: "Readiness probe"
      tags:
      - Service state
      responses:
        '200':
          description: OK

  /metrics:
    get:
      summary: "Service metrics"
      description: "Prometheus-style service metrics"
      tags:
      - Service state
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: "#/components/schemas/metrics_response"

  /debug:
    get:
      summary: "Golang net http pprof"
      description: "Runtime profiling data in the format expected by the pprof visualization tool (https://golang.org/pkg/net/http/pprof/)"
      tags:
      - Service state
      responses:
        '200':
          description: OK

  /vms:
    get:
      summary: "Virtual Machines UUIDs and names list"
      description: Returns VMs list from default directory.
      tags:
      - Virtual Machines
      parameters:
      - name: X-Request-ID
        in: header
        schema:
          type: string
          format: uuid
      - name: datacenter
        in: query
        description: Datacenter name
        schema:
          type: string
          format: uuid
          minimum: 1
      - name: folder
        in: query
        description: Folder name to find VMs in. If the parameter was set 'resource_pool' will be ignored.
        schema:
          type: string
      - name: resource_pool
        in: query
        description: Resource pool to find VMs in. If 'folder' parameter was passed this parameter will be ignored.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/vms_list_response"
    post:
      summary: Deploy OVA file
      description: Deploy OVA file
      tags:
      - Virtual Machines
      parameters:
      - name: X-Request-ID
        in: header
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deploy_ova_body'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/with_task_id_response"

  /vms/{vm_uuid}:
    get:
      summary: "Get information about VM"
      tags:
      - Virtual Machines
      parameters:
      - name: X-Request-ID
        in: header
        schema:
          type: string
          format: uuid
      - name: vm_uuid
        in: path
        required: true
        description: VM UUID
        schema:
          type: string
          format: uuid
          minimum: 1
      - name: datacenter
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/vm_info_response"
    delete:
      summary: Delete Virtual Machine
      tags:
      - Virtual Machines
      parameters:
      - name: X-Request-ID
        in: header
        schema:
          type: string
          format: uuid
      - name: vm_uuid
        in: path
        required: true
        description: VM UUID
        schema:
          type: string
          format: uuid
          minimum: 1
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                datacenter:
                  type: string
                  example: DC1
      responses:
        '200':
          description: OK

  /vms/{vm_uuid}/snapshots:
    get:
      summary: "List of VM snapshots"
      tags:
      - Virtual Machines
      - Snapshots
      parameters:
      - name: X-Request-ID
        in: header
        schema:
          type: string
          format: uuid
      - name: vm_uuid
        in: path
        required: true
        description: VM UUID
        schema:
          type: string
          minimum: 1
          format: uuid
      - name: datacenter
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/snapshots"
    post:
      summary: "Create VM snapshot"
      tags:
      - Virtual Machines
      - Snapshots
      parameters:
      - name: X-Request-ID
        in: header
        schema:
          type: string
          format: uuid
      - name: vm_uuid
        in: path
        required: true
        description: VM UUID
        schema:
          type: string
          minimum: 1
          format: uuid
        examples:
          vm:
            summary: test
            value: vm1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_snapshot_body'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/create_snapshot_response"

  /vms/{vm_uuid}/snapshots/{snapshot}:
    delete:
      summary: "Delete VM snapshot"
      tags:
      - Virtual Machines
      - Snapshots
      parameters:
      - name: X-Request-ID
        in: header
        schema:
          type: string
          format: uuid
      - name: vm_uuid
        in: path
        required: true
        description: VM UUID
        schema:
          type: string
          format: uuid
          minimum: 1
      - name: snapshot
        description: Snapshot ID
        in: path
        required: true
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: OK

  /vms/{vm_uuid}/revert/{snapshot}:
    post:
      summary: "Restore VM from snapshot"
      tags:
      - Virtual Machines
      - Snapshots
      parameters:
      - name: X-Request-ID
        in: header
        schema:
          type: string
          format: uuid
      - name: vm_uuid
        in: path
        required: true
        description: VM UUID
        schema:
          type: string
          minimum: 1
          format: uuid
      - name: snapshot
        in: path
        required: true
        description: Snapshot ID
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: OK

  /vms/{vm_uuid}/revert:
    post:
      summary: "Restore VM from current snapshot"
      tags:
      - Virtual Machines
      - Snapshots
      parameters:
      - name: X-Request-ID
        in: header
        schema:
          type: string
          format: uuid
      - name: vm_uuid
        in: path
        required: true
        description: VM UUID
        schema:
          type: string
          minimum: 1
          format: uuid
      - name: snapshot
        in: path
        required: true
        description: Snapshot ID
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: OK

  /vms/{vm_uuid}/roles:
    patch:
      summary: "Add role to VM"
      tags:
      - Virtual Machines
      - Permissions
      parameters:
      - name: X-Request-ID
        in: header
        schema:
          type: string
          format: uuid
      - name: vm_uuid
        in: path
        required: true
        description: VM UUID
        schema:
          type: string
          minimum: 1
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/vm_add_role_body'
      responses:
        '200':
          description: OK
        '500':
          description: Error
          content:
            application/json::
              schema:
                $ref: "#/components/schemas/vm_add_role_error_response"

  /vms/{vm_uuid}/power:
    patch:
      summary: "Change Virtual Machine power state"
      tags:
      - Virtual Machines
      - Power
      parameters:
      - name: X-Request-ID
        in: header
        schema:
          type: string
          format: uuid
      - name: vm_uuid
        in: path
        required: true
        description: VM UUID
        schema:
          type: string
          minimum: 1
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/vm_change_power_body'
      responses:
        '200':
          description: OK
        '500':
          description: Error

  /vms/{vm_uuid}/screenshot:
    patch:
      summary: "Get Virtual Machine console screenshot"
      tags:
      - Virtual Machines
      - Screenshot
      parameters:
      - name: X-Request-ID
        in: header
        schema:
          type: string
          format: uuid
      - name: vm_uuid
        in: path
        required: true
        description: VM UUID
        schema:
          type: string
          minimum: 1
          format: uuid
      - name: datacenter
        in: query
        description: Datacenter name
        schema:
          type: string
          format: uuid
          minimum: 1
      responses:
        '200':
          description: OK
          content:
            image/png:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                $ref: "#/components/schemas/vm_not_found_error"
        '500':
          description: Error

  /vms/{vm_uuid}/rename:
    patch:
      summary: "Rename Virtual Machine"
      tags:
      - Virtual Machines
      parameters:
      - name: X-Request-ID
        in: header
        schema:
          type: string
          format: uuid
      - name: vm_uuid
        in: path
        required: true
        description: VM UUID
        schema:
          type: string
          minimum: 1
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/vm_rename_body'
      responses:
        '200':
          description: OK
        '500':
          description: Error

  /permissions/roles:
    get:
      summary: "List roles"
      tags:
      - Permissions
      parameters:
      - name: X-Request-ID
        in: header
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/permissions_roles_response"

  /find/vm:
    get:
      summary: "Find VM by path"
      tags:
      - Find
      parameters:
      - name: X-Request-ID
        in: header
        schema:
          type: string
          format: uuid
      - name: path
        in: query
        required: true
        description: Virtual Machine name or path. Wildcard supported.
        schema:
          type: string
      - name: datacenter
        in: query
        description: Datacenter name
        schema:
          type: string
          format: uuid
          minimum: 1
      responses:
        '200':
          description: OK
          content:
            application/json::
              schema:
                $ref: "#/components/schemas/vm_name_uuid_response"
        '500':
          description: Error
          content:
            application/json::
              schema:
                $ref: "#/components/schemas/find_vm_error_response"

  /tasks/{task_id}:
    get:
      summary: "Get information about backgroud task"
      tags:
      - Tasks
      parameters:
      - name: X-Request-ID
        in: header
        schema:
          type: string
          format: uuid
      - name: task_id
        in: path
        required: true
        description: Task ID
        schema:
          type: string
          format: uuid
          example: 6ef18379-6220-6f7e-30ca-1d1c20a3cc97
      responses:
        '200':
          description: OK
          content:
            application/json::
              schema:
                $ref: "#/components/schemas/task_id_response"

components:
  schemas:
    build_info_response:
      type: object
      properties:
        build_time:
          type: string
          format: date-time
        commit:
          type: string
          example: "c0c5f0a"

    metrics_response:
      type: string
      example: |-
        # HELP duration_API_request_duration_seconds Request duration in seconds.
        # TYPE duration_API_request_duration_seconds summary
        duration_API_request_duration_seconds{method="VMSnapshotsList",success="true",quantile="0.5"} 0.886037501
        duration_API_request_duration_seconds{method="VMSnapshotsList",success="true",quantile="0.9"} 0.891919249
        duration_API_request_duration_seconds{method="VMSnapshotsList",success="true",quantile="0.99"} 0.891919249
        duration_API_request_duration_seconds_sum{method="VMSnapshotsList",success="true"} 7.092656131
        duration_API_request_duration_seconds_count{method="VMSnapshotsList",success="true"} 8
        # HELP go_gc_duration_seconds A summary of the GC invocation durations.
        # TYPE go_gc_duration_seconds summary
        go_gc_duration_seconds{quantile="0"} 5.8395e-05
        go_gc_duration_seconds{quantile="0.25"} 5.8395e-05
        go_gc_duration_seconds{quantile="0.5"} 6.9086e-05
        go_gc_duration_seconds{quantile="0.75"} 8.9717e-05
        go_gc_duration_seconds{quantile="1"} 8.9717e-05


    vm_name_uuid_response:
      type: object
      required:
        - name
        - uuid
      properties:
        name:
          type: string
          example: "My Virtual Machine 01"
        uuid:
          type: string
          format: uuid

    vms_list_response:
      type: array
      items:
        $ref: '#/components/schemas/vm_name_uuid_response'

    vm_info_response:
      type: object
      properties:
        Config:
          type: object
          example:
            Annotation: Test annotation,
            Name: coreos
        Guest:
          type: object
        HeartBeat:
          type: object
        Runtime:
          type: object
          example:
            BootTime: 2018-05-14T23:18:10Z,
            Paused: true,
            PowerState: poweredOn

    create_snapshot_body:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          example: "MySnapshot"
        description:
          type: string
          example: "This is a snapshot"

    create_snapshot_response:
      type: object
      example:
        "snapshot_id": 8

    snapshots:
      type: object
      properties:
        snapshots:
          type: array
          items:
            type: object
            example:
              name: "snapshot1"
              description: "My snapshot"
              id: 4
              created_at: "2018-05-17T08:54:35.251931Z"

    find_vm_error_response:
      type: object
      example:
        "error": "vm 'my-folder/my-vm' not found"

    vm_add_role_body:
      type: array
      items:
        $ref: '#/components/schemas/role'
      # type: object
      # required:
      # - role_id
      # - principal
      # properties:
      #   role_id:
      #     type: integer
      #     example: 5
      #   principal:
      #     type: string
      #     example: "DOMAIN\\example.user"
      #   datacenter:
      #     type: string
      #     example: "DC1"

    vm_change_power_body:
      type: object
      required:
      - state
      properties:
        state:
          type: string
          enum: ["on", "off", "reboot", "reset", "suspend"]
          example: "on"
        datacenter:
          type: string
          example: "DC1"

    vm_rename_body:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: "New Virtual Machine name"
          example: "My New VM name"
        datacenter:
          type: string
          example: "DC1"

    vm_add_role_error_response:
      type: object
      example:
        "error": "ServerFaultCode: The user or group named 'DOMAIN\\example.user' does not exist."

    role:
      type: object
      required:
        - name
        - id
        - description
      properties:
        name:
          type: string
          example: "VM-Admin"
        id:
          type: integer
          example: -106818344
        description:
          type: object
          properties:
            label:
              type: string
              example: "VM-Admin"
            summary:
              type: string
              example: "VM-Admin"

    permissions_roles_response:
      type: array
      items:
        $ref: '#/components/schemas/role'


    vm_not_found_error:
      type: object
      properties:
       error:
        type: string
        example: "could not find Virtual Machine by UUID. Could not assert reference to Virtual Machine"

    task_id_response:
      type: object
      required:
        - stage
      properties:
        stage:
          type: string
          example: complete
        message:
          type: string
          example: ok
        ip:
          type: array
          items:
            type: string
          example: ["10.10.20.110", "10.10.30.200"]

    deploy_ova_body:
      type: object
      required:
        - name
        - ova_url
        - datastores
        - networks
        - computer_resources
      properties:
        name:
          type: string
          example: Janna VM
        ova_url:
          type: string
          format: uri
          example: https://stable.release.core-os.net/amd64-usr/current/coreos_production_vmware_ova.ova
        datacenter:
          type: string
          example: DC1
        folder:
          type: string
          example: Dev VMs
        annotation:
          type: string
          example: This is an annotation of the deployed VM
        datastores:
          type: object
          properties:
            type:
              type: string
              description: "Storage type. If 'cluster' type was chosen then Janna try to get DRS recommendation to choose proper 'datastore'."
              enum: [cluster, datastore]
              example: cluster
            names:
              type: array
              items:
                type: string
                description: List of storages. One of them will be chosen randomly.
                example: DatastoreCluster1
          required:
            - type
        networks:
          type: object
          description: Network defines a mapping from each network inside the OVF to a ESXi network. The networks must be presented on the ESXi host.
          example:
            "VM Network": "esxi-net1"
        computer_resources:
          type: object
          properties:
            type:
              type: string
              description: "Computer resource type."
              enum: [host, cluster, rp]
              example: cluster
            path:
              type: string
              description: Name or path to a computer resource. The parameter Can be omitted, then Janna will try to get default computer resource.
              example: my-esxi-cluster
          required:
            - type

    with_task_id_response:
      type: object
      properties:
        task_id:
          type: string
          format: uuid
      example:
        "task_id": "548f65e9-2f79-2af9-8641-be75088f43c5"