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 

1. 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)

2. 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)

3. Check that the user has admin permissions: 

   Check access permissions

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

Receiving task statuses 

1. 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]

2. 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

1. 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)

2. 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

3. 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)

4. Save the user ID. It can be retrieved from account_info (step 2) or after registration (step 3). 
5. 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. 

6. 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)

7. Wait when the operation is completed.

Operations with VM

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

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

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

Operations with IP addresses

The following examples are for IPv4. 

Adding an IP address

1. 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]

2. 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)

Adding a specific 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)

Deleting the IP address 

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

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: 

1. 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"}}
   }}')

2. 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"}}
   }}')

3. 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)

4. 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)

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