This is an old revision of the document!


Client API

Stallion 2 provides an end-user API that emulates the same calls/returns as SolusVM and provides some additional features.

A 'version 2' of our API will be developed along side our new billing panel. We plan to have all controls (create, delete, reinstall, etc) all available within the new API.

Initial Requirements

Calls are made over standard HTTPS. Both GET & POST calls are supported.

You must have your 'key' and 'hash' values from the 'Settings' tab of your virtual server, as well as the API enabled.

Example API details

URL's, Actions, & Global Variables

You may access the API at the following URL's.

URL Description Returns
https://manage.buyvm.net/api/client/command.php SolusVM emulating API. Also known as 'v1' XML

Possible Actions

The following table describes each possible action. An action must always be passed.

Action Description Returned data example
boot Boot the virtual server <status>success/failed</status><statusmsg>booted</statusmsg>
reboot Reboot the virtual server <status>success/failed</status><statusmsg>rebooted</statusmsg>
shutdown Shutdown the virtual server <status>success/failed</status><statusmsg>shutdown</statusmsg>
info returns information about the virtual server
rdns Apply Reverse DNS on an IP address See more below

POST/GET Fields

These fields can provide additional information with every request.

Field Description Virtulization Returned data example Required?
action Which action to call ALL See actions table Yes
bw Returns bandwidth statistics in bytes ALL <bw>total,used,free,percentage</bw> No
hdd Returns disks pace statistics in bytes OpenVZ <hdd>total,used,free,percentage</hdd> No
mem Returns memory statistics in bytes OpenVZ <mem>total,used,free,percentage</mem> No
ipaddr Returns all bound IP addresses ALL <ipaddr>1.2.3.4,2.3.4.5,4.5.6.7,7.8.9.10</ipaddr> No
location Returns location information ALL <location>Las Vegas, Nevada, USA</location> No
status Returns the online/offline status ALL <statusmsg>online</statusmsg> No

Setting Reverse DNS

Applying Reverse DNS requires additional fields.

Field Description Required?
ip IP Address you want Reverse DNS applied to Yes
rdns What you want the Reverse DNS set to Yes

You must provide it an IP address bound to the virtual server in question as well as a valid RDNS entry. Failing to do so will cause a <status> of error to be returned and a <statusmsg> detailing which error you triggered.

NOTICE: Due to a lighttpd bug, please add the following to your cURL options when making an rDNS call

curl_setopt($ch, CURLOPT_HTTPHEADER, array('Expect:'));

PHP Example

The following example was cleaned up but based mostly on http://docs.solusvm.com/client_api

<?php
 
$url = "https://manage.buyvm.net/api/client/command.php";
 
$post = array(
	'key' => 'YOUR-KEY-HERE',
	'hash' => 'EXAMPLE-HASH-HERE',
	'action' => 'reboot',
	'bw' => 'true',
	'hdd' => 'true',
	'mem' => 'true',
	'ipaddr' => 'true',
	'status' => 'true'
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
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_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Expect:'));

$data = curl_exec($ch);

curl_close($ch);
  
preg_match_all('/<(.*?)>([^<]+)<\/\\1>/i', $data, $match);

$result = array();

foreach ($match[1] as $x => $y) {
	$result[$y] = $match[2][$x];
}

?>

Gotcha's

As of December 2014, the the ipaddr option only shows IP addresses the virtual server in question owns, not ones it has available in failover.

Due to the nature of this API, and the need of keeping it compatible with SolusVM applications, there isn't an easy way to mark what's in failover, anycast, or anything like that.