===== 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.
{{:clientapiimage.png?400|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//

<code>curl_setopt($ch, CURLOPT_HTTPHEADER, array('Expect:'));</code>
==== PHP Example ====

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

<code>
<?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];
}

?>
</code>

==== 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.