VMmanager 6: Administrator guide

API guide

ISPSystem

General information 


API URL

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
{
  "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 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":3004,
        "msg":"Unavailable"
      }
    }
  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>
}

<time> — token expiration date in YYYY-MM-DD HH:MM:SS format 

<comment> — arbitrary 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'

Authorization by session number

  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 JSON response: 

    Successful authorization
    {
      "expires_at": string,
      "id": int,
      "session": string
    }
    Authorization error
    {
      "error":
      {
        "code": 1114,
        "msg": "Whoami verifired error",
        "value":
        {
          "code": 3002,
          "msg": "Session not found"
        }
      }
    }
  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'

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

  1. Create a user in VMmanager for temporary access.

  2. Connect to the server with VMmanager via SSH with superuser permissions.
  3. Enter the command:

    docker exec vm_box curl -X POST http://input:1500/auth/v4/user/<user_id>/key -d '{}' -H 'internal-auth:on'

    <user_id> — account ID. Usually, ID of the first administrator account is 3. To get a complete list of accounts with IDs, enter the command:

    docker exec vm_box curl -X GET http://input:1500/auth/v3/user -H 'internal-auth:on'


    In response, you will get the message in the form:

    Example of response
    {"id":"8","key":"8-c46c0204-873a-4a69-b34d-d8b1e93e06d7"}

    id — the sequence number of the key

    key — access key

The user will be able to log in to the platform via a link in the following format: https://domain.com/auth/key/<key>

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

<key> — access key

The key is valid for one hour.

Thank you for your feedback!
Was the article useful?
Tell us why not:

it does not match the title

it was hard to understand

I didn't find the answer

recommendations from the article did not help

other

Tell us what you didn't like in the article: