clientapi [Frantech/BuyVM Wiki]

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.

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.