API guide

General information

API URL

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

Where

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

{
  "error":
  {
    "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:
                break
    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
```
domain.com/vm/v3/host/host_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
```
domain.com/vm/v3/host/
```

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

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
}
```
Handle the response. It can contain error messages or JSON like:
Response in JSON
```
{
  "expires_at": string,
  "id": int,
  "session": string
}
```
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'
```

In the case of error you will receive the following message:

Authorization error

{
  "error":
  {
    "code": 1114,
    "msg": "Whoami verifired error",
    "value":
    {
      "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:

Log in to VMmanager as Admin.
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.
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.

VMmanager 6: Administrator guide