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>
}
}
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 IDdomain.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 VMdomain.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 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
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":3004, "msg":"Unavailable" } }Use the token value that you have received in the heading of the HTTP request. E.g.:
Usage in curlcurl -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:
{
"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'
Authorization by session number
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 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" } } }Use the session number that you have received in the heading of the HTTP request. E.g.:
Usage in curlcurl -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.
Create a user in VMmanager for temporary access.
- Connect to the server with VMmanager via SSH with superuser permissions.
Enter the command:
docker exec vm_box curl -X POST http://input:1500/auth/v4/user/<user_id>/key -d '{}' -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"}
The user will be able to log in to the platform via a link in the following format: https://domain.com/auth/key/<key>
The key is valid for one hour.