Using SolusVM API: examples, tips and tricks

This post is for beginners mostly that wants to start using SolusVM API but do not know how to start with it.

API can be useful when you are trying to develop an application that will communicate with other application or software like SolusVM. For example, monitoring application for cell phones or the module for billing system that allows managing virtual servers from the billing software. Or you can simply create a script that will do mass un-suspend for all virtual servers in one run.

The methods available are described on the official documentation page here https://documentation.solusvm.com/display/DOCS/API . It is updated each time when new API method added.

API request consists of 3 main parts: Action, Method and Variables

Action is the action we want to perform remotly, like create a virtual server, mount ISO image, suspend/unsuspend virtual servers, etc.
Method is the one of the HTTP requests methods (https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) Mostly this is GET, POST methods
Variables are the set of parameters sent on SolusVM Master API interface (/api/admin/command.php or /api/client/command.php) like a virtual server ID, required IP address, etc.

It is a common practice putting API calls into PHP scripts. It can be invoked directly from command line:
php /path/to/script.php
OR placed into website document root and invoked using browser https://domain.com/script.php

API ID/KEY are used for the authentication on SolusVM. It is required to browse to Dashboard > Configuration > API Access and API user. It is binded to the IP address of the server where the script is executed.

Here are few examples of PHP scripts that using SolusVM REST API:

1. Create a virtual server

---------------------------------------------------------------------------------
<?php
// Url to the admin API
$url = "https://IP_ADDRESS:5656/api/admin";
$postfields["id"] = "hashed_id";
$postfields["key"] = "hashed_key";
$postfields["action"] = "vserver-create";

$postfields["type"]="kvm";
$postfields["node"] = "kvmc7node";
$postfields["hostname"] = "my.virtualserver.tld";
$postfields["plan"] = "service1";
$postfields["template"] = "linux-centos-7-x86_64-minimal-latest";
$postfields["nodegroup"] = "0";
$postfields["password"] = "qwerty123";
$postfields["username"] = "johndoe";
$postfields["ips"] = "1";
$postfields["randomipv4"] = "true";

// Send the query to the solusvm master
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/command.php");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 900);
curl_setopt($ch, CURLOPT_FRESH_CONNECT, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Expect:"));
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postfields);
$data = curl_exec($ch);
curl_close($ch);

// Parse the returned data and build an array
preg_match_all('/<(.*?)>([^<]+)<\/\\1>/i', $data, $match);
$result = array();
foreach ($match[1] as $x => $y)
{
$result[$y] = $match[2][$x];
}
print_r($match);

echo "================";
echo "";
?>
---------------------------------------------------------------------------------

template name should be a file name of the template without extension, e.g. linux-centos-7-x86_64-minimal-latest instead of linux-centos-7-x86_64-minimal-latest.gz

NOTE: If the execution of the script takes too much time and fails with time out error, consider tuning CURLOPT_TIMEOUT option

2. List all virtual servers:

---------------------------------------------------------------------------------
<?php
// Url to the admin API
$url = "https://IP_ADDRESS:5656/api/admin";
$postfields["id"] = "hashed_id";
$postfields["key"] = "hashed_key";
$postfields["action"] = "node-virtualservers";
$postfields["nodeid"]="2";

// Send the query to the solusvm master
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/command.php");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 900);
curl_setopt($ch, CURLOPT_FRESH_CONNECT, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Expect:"));
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postfields);
$data = curl_exec($ch);
curl_close($ch);

// Parse the returned data and build an array
preg_match_all('/<(.*?)>([^<]+)<\/\\1>/i', $data, $match);
$result = array();
foreach ($match[1] as $x => $y)
{
$result[$y] = $match[2][$x];
}
print_r($match);

echo "================";
echo "";
?>
---------------------------------------------------------------------------------

3. Fetching the information about the virtual server
---------------------------------------------------------------------------------
<?php
// Url to the admin API
$url = "https://IP_ADDRESS:5656/api/admin";
$postfields["id"] = "hashed_id";
$postfields["key"] = "hashed_key";
$postfields["vserverid"]="246";

// Send the query to the solusvm master
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/command.php");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 900);
curl_setopt($ch, CURLOPT_FRESH_CONNECT, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Expect:"));
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postfields);
$data = curl_exec($ch);
curl_close($ch);

// Parse the returned data and build an array
preg_match_all('/<(.*?)>([^<]+)<\/\\1>/i', $data, $match);
$result = array();
foreach ($match[1] as $x => $y)
{
$result[$y] = $match[2][$x];
}
print_r($match);

echo "================";
?>
---------------------------------------------------------------------------------

UPD. Sometimes API request fails to execute or return a response with timeout error. In that case consider to adjust curl_setopt($ch, CURLOPT_TIMEOUT, 900); parameter in the script and increase it.