VMmanager 6: Administrator guide

API guide

General information 


Access the API by the URL https://domain.com/service/api_version/function/. 


domain.com — public IP address or the domain of the server with VMmanager. 

service — internal service for processing requests: auth or vm. 

api_version — current version API: v3.

function — function to be executed in VMmanager.

HTTP-request methods 

VMmanager supports GET, POST, and DELETE.

POST-request methods 

To send parameters for a POST-request, specify them in the request body in the JSON format. 

Response format

A response to API-requests is sent in the form of JSON-objects, e.g.:

Error notification in JSON
    "code": <error internal code, int>,
    "msg": <error message, string>,
    "value": <additional information, object>

How to process code 503

If VMmanager is not active for a long time it can be suspended. The API-requests will be terminated with code 503. Repeat the requests until you receive another code: 

Example on Python 3
def retry(fn, **kwargs):
    response = fn(**kwargs)
    if response.status_code == 503:
        for attempt in range(1, 11):
            time.sleep(0.1 * attempt)
            logging.info(f'Try connect to {kwargs["url"]} number {attempt}')
            response = fn(**kwargs)
            if response.status_code != 503:
    return response

def internal_post(url, data):
    headers = {"Host": "instance-" + os.environ["INSTANCE_ID"], "internal-auth": "on"}
    logging.info(f'Try connect to {url} with headers {headers}')
    retry(requests.post, url=url, json=data, headers=headers)

Filters in requests

VMmanager supports two GET-requests: 

  • the information about a certain element by its ID — the response will contain the information about the specified element. It won't contain the information about associated elements such as IP address, cluster, and VM disk. E.g.: 

    Receive information about VM by ID
  • a full list of elements of a certain type — the response will contain a full list of all elements of the specified type. The response will also contain information about all items. E.g.: 

    Receive information about all VM

We recommend requesting a full list of elements and applying filters to it. This allows receiving information about all associated items.  

Filter formats

Available filters: 

  • WHERE — similar to the expression WHERE in SQL. It supports the processing of logical operators AND, OR, NOT. Comparison parameters:
    • EQ — equal;
    • NE — not equal;
    • GT — larger;
    • GE — larger than or equal to;
    • LT — less;
    • LE — less than or equal to;
    • CP — search for values by the specified mask.  Similar to the operator LIKE in SQL;
  • ORDERBY — sort by the specified parameter. If the sorting is not specified, the list will be sorted in ascending order by ID. Possible order:
    • ASC — in ascending order;
    • DESC — in descending order;
  • LIMIT — output the range of filtered elements. Enter two comma-separated digits as values. The numbering starts with 0. 

Filter rules

  • put ? before the first filter;
  • use = to specify the filter values and parameters;
  • put digital and text values in single quotes;
  • separate parameters, values, and logical operations of the filter with +;
  • put conditions of the filter WHERE into brackets. To group conditions, use the logical operations AND, OR and NOT;
  • group several filters with &.

Examples of requests with filters

Get the cluster with ID 1
GET https://domain.com/vm/v3/cluster?where=(id+EQ+'1')
Get the task by ID in consul and name
GET https://domain.com/vm/v3/task?where=(consul_id+EQ+'1341774670')+AND+(name+EQ+'host_create')
Get a list of 50 VM in descending order by name
GET https://domain.com/vm/v3/host?orderby=cluster.name+desc&limit=0,50

Authentication methods 

Authentication is required for API-requests in VMmanager.

Login and password authentication

  1. To receive a session number, send the POST-request to a URL like https://domain.com/auth/v3/auth. 

    Request body in JSON
      "email": your_email,
      "password": your_password
  2. Handle the response. It can contain error messages or JSON like: 

    Response in JSON
      "expires_at": string,
      "id": int,
      "session": string
  3. Use the session number that you have received in the heading of the HTTP request. E.g.:

    Usage in curl
    curl -k -H "Cookie:ses6=F2BABF12426B297C86FC5628" 'https://domain.com/vm/v3/host'
  4. In the case of error you will receive the following message: 

    Authorization error
        "code": 1114,
        "msg": "Whoami verifired error",
          "code": 3002,
          "msg": "Session not found"

Key authentication 

VMmanager supports throughout user authentication with an admin login and password. Eg. it can be used to redirect authorized users from BILLmanager to VMmanаger 6.

How it works:

  1. Log in to VMmanager as Admin.
  2. To generate an authentication key, send the POST-request to the URL like https://domain.com/auth/v3/user/user_email/key. The response will contain a JSON-object with the key field.  
  3. To receive the session number, send the POST-request to the URL like  https://domain.com/auth/v3/auth_by_key. In the request body, specify the key that you have received on step 2.