API guide

General information 

API URL

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

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":
  {
    "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":
  {
    "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: 

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

  CODE

• 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/

  CODE

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 https://domain.com/vm/v3/cluster?where=(id+EQ+1)

GET https://domain.com/vm/v3/task?where=(consul_id+EQ+'1341774670')+AND+(name+EQ+'host_create')

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
   }

   CODE

2. Handle the JSON response: 

   Successful authorization

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

   CODE

   Authorization error

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

   CODE

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'

   CODE

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: 

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

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

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:

{
"value": "<time>"
}

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

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

   CODE
    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"}'

   CODE

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

   CODE
    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

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

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

   CODE
    Comments

   id — key id

   key — key value

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

   CODE

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

   CODE
    Comments

   id — token id

   token — token number

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'

   CODE

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

   Authorization error

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

   CODE

Useful tips

Related topics:

• Examples of how to use API
• VMmanager API
• Auth API v4