API guide

General information

API URL

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

Where

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>
  }
}

Permissions

Some functions are not available for external API requests. A request to such functions will return an error 3001 Unauthorized:

Error notification

{
  "error":
  {
    "code": 3001,
    "msg":"Unauthorized"
  }
}

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 text values in single quotes. For numeric values the use of quotes is optional;
separate parameters, values, and logical operations of the filter with space or %20 character. In the curl parameter, use the + character to separate;
you may put conditions of the filter WHERE into brackets;
to group conditions, use the logical operations AND, OR and NOT;
group several filters with &;
when using the CP operator, add the percent character (%25) to the beginning and end of the mask.
Example request
```
where=(id%20CP%20'%25some_text%25')
```

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.

Authorization by token

To receive a session number, send the POST-request to a URL like https://domain.com/auth/v4/public/token.
Request body in JSON
```
{
  "email": your_email,
  "password": your_password
}
```

Handle the JSON response:

Successful authorization

{
  "id": int,
  "token": string
}

Authorization error

{
  "error": {
    "code": 22013,
    "msg": "Invalid password"
  }
}

Use the token value that you have received in the heading of the HTTP request. E.g.:

Usage in curl

curl -X POST 'https://domain.com/vm/v3/host/' -H 'x-xsrf-token: 4-e9726dd9-61d9-2940-add3-914851d2cb8a'

If the authorization token has not been used within 60 minutes, it will be deleted. To get a token with the desired lifetime, send the POST-request to a URL like https://domain.com/auth/v4/token:

Request body in JSON

{
"expires_at": <time>,
"description": <comment>
}

Пояснения

The response will contain a new token with a specified expiration date.

Usage in curl

curl -X POST 'https://domain.com/auth/v4/token' -d '{"expires_at": "2030-01-31 00:00:00", "description": "Token for integration"}' -H 'x-xsrf-token: 4-e9726dd9-61d9-2940-add3-914851d2cb8a'

Changing token and session lifetime

By default, the token lifetime is 60 minutes. To change this setting, send a POST request to a URL like https://domain.com/auth/v4/setting/token_ttl:

Request body in JSON

{
"value": "<time>"
}

Comments

Usage in curl

curl -X POST 'https://domain.com/auth/v4/setting/token_ttl' -d '{"value": "999"}' -H 'x-xsrf-token: 4-e9726dd9-61d9-2940-add3-914851d2cb8a'

You also can change the session lifetime via interface. Read more in the Session lifetime.

Key authentication

VMmanager supports throughout user authorization with admin login and password. Eg. it can be used to redirect authorized users from a billing system to VMmanager or to provide temporary access to the platform for a user. The duration of this key is one hour.

Send the POST-request to the URL like https://domain.com/auth/v4/public/token.
Request body in JSON
```
{
  "email": "admin@example.com",
  "password": "secret"
}
```
Comments

admin@example.com — platform administrator email
secret — platform administrator password
Usage in curl
```
curl -X POST 'https://domain.com/api/auth/v4/public/token' -d '{"email": "admin@example.com", "password": "secret"}'
```
Handle the response. It may contain error messages or JSON like this:
Response in JSON
```
{
  "confirmed":true, 
  "expires_at": null,
  "id":"24",
  "token":"24-cee181d2-ccaa-4b64-a229-234aa7a25db6"
}
```
Comments

id — token id
token — token number

Note

With this key you can give the user temporary access to the platform. The user will be able to log in to the platform via a link in the following format: https://domain.com/auth/key/<key>
Comments

domain.com — domain name or IP address of the server with VMmanager
<key> — access key
Send a POST-request to create the key:
Create the authentication key
```
curl -X POST 'https://domain.com/api/auth/v4/user/client@example.com/key'  -H 'x-xsrf-token: 24-cee181d2-ccaa-4b64-a229-234aa7a25db6' -H 'isp-box-instance: true'  -d '{}'
```
Comments
client@example.com — email of the account for which the key is generated. You can use the account id instead of email
You will receive a JSON-object like this:
Response in JSON
```
{
  "id":"4",
  "key":"4-74e7c0e9-a5ff-4f52-a2ac-ed03c6ed1e21"
}
```
Comments

id — key id
key — key value

To get the value of a token using a temporary key, send a POST request:

Receive the session number by the key

curl -k -X POST 'https://domain.com/api/auth/v4/public/key' -H "isp-box-instance: true" -d '{"key": "4-74e7c0e9-a5ff-4f52-a2ac-ed03c6ed1e21"}'

You will receive the JSON-object like this:

Response in JSON

{
  "confirmed":true,
  "expires_at": null,
  "id":"123",
  "token":"1996-0082f9c6-0b07-43ca-b4e7-449c6b0df71f"
}

Comments

Use the token that you have received in the heading of the HTTP request. E.g.:

Usage in curl

curl -X GET 'https://domain.com/vm/v3/host' -H 'x-xsrf-token: 1996-0082f9c6-0b07-43ca-b4e7-449c6b0df71f' -H 'isp-box-instance: true'

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

Authorization error

{
  "error":
  {
    "code": 3001,
    "msg":"Unauthorized"
  }
}

Useful tips