API:Client

From SolusVM

Overview

The client API is a http based API that allows you and your clients to interact directly with a virtual server with security and ease. The client API can be disabled at any time and access is only granted with a key and hash on a per vps basis.

Currently available options are: Reboot, Boot, Shutdown and status report (online/offline).

Functions

Reboot virtual server

Function .............. : Reboot virtual server
Action ................ : reboot
Method ................ : GET or POST

Returned values ....... : <status>success</status>
                          <statusmsg>rebooted</statusmsg>                                                       

Boot virtual server

Function .............. : Boot virtual server
Action ................ : boot
Method ................ : GET or POST

Returned values ....... : <status>success</status>
                          <statusmsg>booted</statusmsg>                                                       

Shutdown virtual server

Function .............. : Shutdown virtual server
Action ................ : shutdown
Method ................ : GET or POST

Returned values ....... : <status>success</status>
                          <statusmsg>shutdown</statusmsg>                                                                                

Virtual server status

Function .............. : Get virtual server status
Action ................ : status
Method ................ : GET or POST

Returned values ....... : <status>success</status>
                          <statusmsg>online|offline</statusmsg>                                                                                

Virtual server information

Function .............. : Get virtual server information. Setting any flag to true will return the result.
Action ................ : info
Method ................ : GET or POST
Flags ................. : ipaddr (Returns a list of ipaddresses)
                          hdd    (Returns the hard disk usage in Bytes) 
                          mem    (Returns the memory usage in Bytes)
                          bw     (Returns the bandwidth usage in Bytes)                           

Returned values ....... : <ipaddr>123.123.123.123,122.122.122.122,111.111.111.111</ipaddr>
                          <hdd>total,used,free,percentused</hdd> 
                          <mem>total,used,free,percentused</mem>
                          <bw>total,used,free,percentused</bw>
                                                                              

Extras

The following are also retuned on a success status:

                          <hostname>[hostname]</hostname>
                          <ipaddress>[mainipaddress]</ipaddress>

You can also specify the status to be returned on any of the queries by adding status=true to the query. The returned data will then also contain:

                          <vmstat>online|offline</vmstat>

PHP Code Examples

Example connection script

<?php
 
// Url to the client API
 
$url = "https://<MASTER IP>:5656/api/client";
 
// Specify the key, hash and action
 
$postfields["key"] = "EXAMPLE-API-KEY";
$postfields["hash"] = "exaMpleHasH";
$postfields["action"] = "reboot"; // reboot, shutdown, boot, status
 
// 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, 20);
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, $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];
}
 
?>

Output all returned data

<?php
 
print_r($result);
 
?>

Parsing returned data

<?php
 
// Check for any errors
 
if ($result["status"] == "error")
{
	echo $result["statusmsg"];
	exit();
}
 
// Display a message on a successful return
 
if ($result["status"] == "success")
{
	if ($result["statusmsg"] == "online")
	{
		echo "The virtual server is online!";
	} elseif ($result["statusmsg"] == "offline")
	{
		echo "The virtual server is offline!";
	} elseif ($result["statusmsg"] == "rebooted")
	{
		echo "The virtual server has been rebooted!";
	} elseif ($result["statusmsg"] == "shutdown")
	{
		echo "The virtual server has been shutdown!";
	} elseif ($result["statusmsg"] == "booted")
	{
		echo "The virtual server has been booted!";
	}
	else
	{
		echo "Status message unknown!";
	}
}
 
?>