VMmanager: Administrator guide

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

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

  1. 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
    }
  2. Handle the JSON response: 

    Successful authorization
    {
      "id": int,
      "token": string
    }
    Authorization error
    {
      "error": {
        "code": 22013,
        "msg": "Invalid password"
      }
    }
  3. 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.

  1. 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
    Usage in curl
    curl -X POST 'https://domain.com/api/auth/v4/public/token' -d '{"email": "admin@example.com", "password": "secret"}'
  2. 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
    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
  3. 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

    You will receive a JSON-object like this: 

    Response in JSON
    {
      "id":"4",
      "key":"4-74e7c0e9-a5ff-4f52-a2ac-ed03c6ed1e21"
    }
    Comments
  4. 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
  5. 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"
      }
    }