openapi: 3.1.0

info:

contact:

email: [email protected]

description: OpenAPI specification for virtual machine management on Ghaf platform

license:

name: Apache License 2.0

identifier: Apache-2.0

title: Virtual Machine Management API of the Ghaf platform - OpenAPI

version: 1.0.1

externalDocs:

description: Find out more about the Ghaf platform

url: https://github.com/tiiuae/ghaf

servers:

- description: The primary server

url: https://localhost/api/v1

- description: The test server

url: https://localhost/api/test/v1

tags:

- description: Operations of virtual machines

name: vm

paths:

/vm/list:

get:

description: Gets list of IDs for all virtual machines

operationId: getVmList

responses:

"200":

content:

application/json:

schema:

items: {}

description: List of IDs for all virtual machines

default:

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorModel'

description: error payload

summary: Get list IDs for all virtual machines

tags:

- vm

/vm/info/{id}:

get:

description: Gets the virtual machine information by ID

operationId: getVmInfoById

parameters:

- description: The ID of the virtual machine

explode: false

in: path

name: id

required: true

schema: {}

style: simple

responses:

"200":

content:

application/json:

schema:

$ref: '#/components/schemas/VirtualMachineInfo'

description: successful operation

"400":

description: Invalid virtual machine ID

"404":

description: Virtual machine ID is valid but not found

default:

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorModel'

description: error payload

summary: Gets virtual machine info by ID

tags:

- vm

/vm/{action}/{id}:

put:

description: Control the virtual machine by ID

operationId: vmAction

parameters:

- description: An action is a command used to control the virtual machine

example: start

explode: false

in: path

name: action

required: true

schema:

enum:

- start

- stop

- pause

style: simple

- description: ID of the virtual machine

example: 101

explode: false

in: path

name: id

required: true

schema: {}

style: simple

responses:

"200":

content:

application/json:

schema:

$ref: '#/components/schemas/VirtualMachineInfo'

description: successful operation

"400":

description: Invalid virtual machine ID

"404":

description: Virtual machine ID is valid but not found

default:

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorModel'

description: error payload

summary: Request to perform a control action on the virtual machine by its ID

tags:

- vm

components:

schemas:

ErrorModel:

properties:

code:

example: 0

message:

example: SomeError#0

required:

- code

- message

VirtualMachineInfo:

example:

memory:

maximumAllocation: 2048

currentAllocation: 2048

totalHost: 8192

performance:

cpuUsage: 50

diskIo: ""

memoryUsage:

numerator: ""

denominator: ""

networkIo: ""

os:

name: Ubuntu

version: 23.04

devices:

list: ""

hypervisorDetails:

emulator: /usr/bin/qemu-system-x86_64

hypervisor: KVM

arch: aarch64

chipset: Q35

firmware: BIOS

cpu:

cores: 4

threads: 8

model: NVidia Tegra X1

sockets: 1

logicalCount: 8

basicDetails:

name: GUI VM

description: GUI Virtual Machine

id: 101

state: R

startTime: ""

runningTime: ""

properties:

basicDetails:

$ref: '#/components/schemas/VirtualMachineBasicDetails'

hypervisorDetails:

$ref: '#/components/schemas/VirtualMachineHypervisorDetails'

cpu:

$ref: '#/components/schemas/VirtualMachineCpu'

memory:

$ref: '#/components/schemas/VirtualMachineMemory'

startTime: {}

runningTime: {}

os:

$ref: '#/components/schemas/VirtualMachineOs'

performance:

$ref: '#/components/schemas/VirtualMachinePerformance'

devices:

$ref: '#/components/schemas/VirtualMachineDevices'

required:

- basicDetails

- cpu

- memory

- os

VirtualMachineBasicDetails:

example:

name: GUI VM

description: GUI Virtual Machine

id: 101

state: R

properties:

id:

example: 101

state:

enum:

- D

- I

- R

- S

- T

- TDebug

- W

- X

- Z

example: R

name:

example: GUI VM

description:

example: GUI Virtual Machine

required:

- id

- name

- state

VirtualMachineHypervisorDetails:

example:

emulator: /usr/bin/qemu-system-x86_64

hypervisor: KVM

arch: aarch64

chipset: Q35

firmware: BIOS

properties:

hypervisor:

enum:

- KVM

example: KVM

arch:

type: string

example: aarch64

emulator:

example: /usr/bin/qemu-system-x86_64

chipset:

example: Q35

firmware:

example: BIOS

VirtualMachineCpu:

example:

cores: 4

threads: 8

model: NVidia Tegra X1

sockets: 1

logicalCount: 8

properties:

model:

example: NVidia Tegra X1

logicalCount:

example: 8

sockets:

example: 1

cores:

example: 4

threads:

example: 8

VirtualMachineMemory:

example:

maximumAllocation: 2048

currentAllocation: 2048

totalHost: 8192

properties:

totalHost:

description: Total host memory in MB

example: 8192

format: int64

currentAllocation:

description: Currently allocated memory by VM in MB

example: 2048

format: int64

maximumAllocation:

description: Maximum possible allocated memory by VM in MB

example: 2048

format: int64

required:

- currentAllocation

- maximumAllocation

- totalHost

VirtualMachineOs:

example:

name: Ubuntu

version: 23.04

properties:

name:

example: Ubuntu

version:

example: 23.04

required:

- name

- version

VirtualMachinePerformance:

example:

cpuUsage: 50

diskIo: 30

memoryUsage: 200

networkIo: 300

properties:

cpuUsage:

type: integer

description: CPU load %

example: 50

memoryUsage:

type: integer

description: Memory usage in MB

diskIo:

type: integer

description: Disk IO in KB/s

networkIo:

type: integer

description: Network IO in KB/s

required:

- cpuUsage

- diskIo

- memoryUsage

- networkIo

VirtualMachineDevices:

example:

list: ""

properties:

list:

items: {}

required:

- list