Examples of how to use API

In this article, you will find simplified examples written on Python 3.6 with the libraries JSON and request.

Checking access level

Log in to VMmanager as Admin:

Authentication

url = "https://vm.example.com/auth/v4/public/token"
data = json.loads('{"email": "admin@example.com", "password": "123456"}')
auth = requests.post(url=url, json=data)

PY

Request the information about the user:

Request information about the user

token = json.loads(auth.content.decode('utf-8')).get('token')
url = "https://vm.example.com/auth/v4/whoami"
cookie = {'x-xsrf-token': f'{token}'}
whoami = requests.get(url=url, headers=cookie)

PY

Check that the user has admin permissions:

Check access permissions

is_admin = '@admin' in json.loads(whoami.content.decode('utf-8')).get('roles')

PY

Receiving task statuses

When a long task is created in VMmanager the response will contain a JSON-object. Use its field task to filter a list of tasks:

Receive information about the task

url = f"https://vm.example.com/vm/v3/task?where=((consul_id+EQ+'{task_id}')+AND+(name+EQ+'{task_name}'))"
response = requests.get(url=url, headers=cookie)
task_info = json.loads(response.content.decode('utf-8')).get('list')[0]

PY

Process the field status in the JSON-object that you have received. Possible values:
- created — the task has been created but it has not been started yet;
- running — the task has been started;
- deferred — the start has been delayed;
- complete — the task has been completed;
- fail — the task has failed.

Creating a VM

Log in to VMmanager as Admin:

Authorization

url = "https://vm.example.com/auth/v4/public/token"
data = json.loads('{"email": "admin@example.com", "password": "123456"}')
auth = requests.post(url=url, json=data)

PY

Make sure that the user is registered in VMmanager:

Search for a user by email

email = "user@example.com"
url = f"https://vm.example.com/vm/v3/account?where=(email+EQ+'{email}')"
account_info = requests.get(url=url, headers=cookie)
user_registered = json.loads(account_info.content.decode('utf-8')).get('size') != 0

PY

Register a user if it is not found:

Add a user

data = json.loads('{"email": "user@example.com", "password": "strong_password", "role": "@user"}')
url = "https://vm.example.com/vm/v3/account"
new_user = requests.post(url=url, json=data, headers=cookie)

PY

Save the user ID. It can be retrieved from account_info (step 2) or after registration (step 3).
Generate VM parameters:
- mandatory — name, root password, cluster ID, account owner ID, list of IP pools;
- optional — domain name;
- resources — amount of CPU, RAM, disk space;
- ID of the os image or VM.

Send the VM creation request:

Create a VM

url = "https://vm.example.com/vm/v3/host"
new_host = requests.post(url=url, json=vm_params, headers=cookie)

PY

Wait when the operation is completed.

Operations with VM

Delete the VM

url = f"https://vm.example.com/vm/v3/host/{host_id}"
deleted_host = requests.delete(url=url, headers=cookie)

PY

Suspend the VM

url = f"https://vm.example.com/vm/v3/host/{host_id}/stop"
data = json.loads('{}')
host = requests.post(url=url, json=data, headers=cookie)

PY

Start the VM

url = f"https://vm.example.com/vm/v3/host/{host_id}/start"
data = json.loads('{}')
host = requests.post(url=url, json=data, headers=cookie)

PY

Operations with IP addresses

The following examples are for IPv4.

Adding an IP address

Receive a list of pools available for the cluster:

Receive cluster IP pools

url = f"https://vm.example.com/vm/v3/cluster?where=(id+EQ+'{cluster_id}')"
cluster_info = requests.get(url=url, headers=cookie)
cluster_ip_pools = json.loads(cluster_info.content.decode('utf-8')).get('list')[0].get('ippools')
ip_pools = [pool['id'] for pool in cluster_ip_pools]

PY

Add the IP address to one of the pools:

Add the IP address

url = f"https://vm.example.com/vm/v3/host/{host_id}/ip"
data = json.loads(f'{{"ipv4_number": {ipv4_number}, "ipv4_pool": {ip_pools}}}')
ip_add = requests.post(url=url, json=data, headers=cookie)

PY

Adding a specific IP address

Add the IP address

url = f"https://vm.example.com/vm/v3/host/{host_id}/ip"
data = {'ip_addr': {'name': ip_str, 'ip_pool': ip_pool_int, 'ip_network': ip_network_int}}
ip_add = requests.post(url=url, json=data, headers=cookie)

PY

Deleting the IP address

Delete the IP

url = f"https://vm.example.com/vm/v3/ip/{ip_id}"
ip_delete = requests.delete(url=url, headers=cookie)

PY

Changing VM resources

Reboot the virtual machine to change the amount of its resources. When starting the task to change resources, the VM will be rebooted automatically. If several tasks are created, the machine will be rebooted several times. To avoid multiple reboots we recommend using delayed tasks:

Describe JSON for the delayed task to change CPU and RAM:

JSON for CPU and RAM

resource_data = json.loads(f'{{
    "cpu_number": {cpu_number},
    "ram_mib": {ram_mib},
    "defer": {{"action": "host_stop"}}
}}')

PY

Describe JSON for the delayed task to change disk space:

JSON for disk

disk_data = json.loads(f'{{
    "size_mib": {hdd_mib},
    "defer": {{"action": "host_stop"}}
}}')

PY

Send the resources change request:

Change CPU, RAM, and disk

resource_url = f"https://vm.example.com/v3/host/{host_id}/resource"
host_change_resource = requests.post(url=resource_url, json=resource_data, headers=cookie)
disk_url = f"https://vm.example.com/v3/disk/{disk_id}"
disk_resize = requests.post(url=disk_url, json=disk_data, headers=cookie)

PY

Restart the virtual machine:

Restart the VM

host_restart_url = f"https://vm.example.com/vm/v3/host/{host_id}/restart"
restart_data = json.loads('{}')
host_restart = requests.post(url=host_restart_url, json=restart_data, headers=cookie)

PY

The response will contain the ID of the tasks task and start_task. Wait when start_task is completed.

Useful tips