One of most powerful features of StormOnDemand is the API.
With the API, you can do anything with your Storm account programmaticaly that you can in the regular web based interface. It's a powerful tool that would allow for things such as automatic instance resizing based on load, emailed load reports, etc. However, I think that the API isn't utilized as much because people might not know how to work with it. What follows is a primer for utilizing PHP to interface with the API (I know PHP much, much, much more than Perl).
Although the documentation might seem a little terse in regards to making calls to the API, it essentially boils down to HTTP POST methods utilizing one of the supported encodings, which are currently JSON, YAML, and XML. Making these calls procedurally can quickly turn your code into something that resembles Italian cuisine, which is why I cobbled together a class to take a more object oriented approach.
The class utilizes the YAML encoding method, as well as the HTTP_REQUEST2 PEAR package. Again, this is just something that I put together, and there are probably much better ways to approach this. But it works. Here is the source:
|PHP |||copy code |||?|
* Author: Jason Gillman Jr.
* Description: This is my attempt at writing a PHP wrapper that will ease Storm API calls with PHP
* It will be designed to use the YAML format for talking with the API server.
* $api_method is as described in docs (Case matters)
* request() method returns an array generated from the API return
// Let's define attributes
private $api_user, $api_pass, $base_url, $api_format, $api_full_uri, $api_request;
private $api_request_body, $api_method, $api_params, $api_return;
function __construct($api_user, $api_pass, $api_method)
// Requires PEAR Package HTTP_Request2
$this->api_user = $api_user;
$this->api_pass = $api_pass;
$this->api_method = $api_method;
$this->base_url = 'https://api.stormondemand.com/';
$this->api_format = 'yaml';
$this->api_full_uri = $this->base_url . $this->api_method . "." .$this->api_format;
function add_param($parameter, $value)
$this->api_request_body['params'][$parameter] = $value;
// HTTP Request goodness
if(isset($this->api_request_body)) // We have params
$api_request = new HTTP_Request2($this->api_full_uri, HTTP_Request2::METHOD_POST); // Instantiate with POST method since we'll be feeding params
$api_request->setHeader('Content-type: application/yaml'); // Specify what you're feeding it
else // No params
$api_request = new HTTP_Request2($this->api_full_uri, HTTP_Request2::METHOD_GET); // Instantiate with GET method since no params
$api_request->setAuth($this->api_user, $this->api_pass, HTTP_Request2::AUTH_BASIC); // Auth stuff
$api_request->setConfig('ssl_verify_peer', FALSE); // This is needed, otherwise HTTP_Request errors last I checked
// Now send the request and get the return on investment
$api_return = $api_request->send();
return yaml_parse($api_return->getBody()); // We now have a nice array of all the returned data
catch (HTTP_Request2_Exception $e)
echo 'Error: ' . $e->getMessage();
One thing that I should mention before continuing is that you need to create an API user. This is done in the interface through Account >> Users
Essentially, you instantiate the class by passing the API username, password, and the API method you are going to be using. The API method comes in the format "First/Second/third" or "First/second" depending on the method you want to use. You don't include the leading slash, and the methods as far as I know are case sensitive.
Once you instantiate the object, you would use the add_param() method in the format of (parameter, value).
Once you add all the parameters (if any), just run the request() method, which will return an array containing the data.
So let's look at a real simple example scenario where you wanted to get the Five Minute load average for a particular server with a uniq_id of '123ABC':
|PHP |||copy code |||?|
require_once(StormAPI.class.php); // Assuming we put the class in this file
$api_user = 'user';
$api_pass = 'pass';
$api_method = 'Monitoring/Load/stats';
$get_load = new StormAPI($api_user, $api_pass, $api_method);
$get_load->add_param('uniq_id', '123ABC'); // Where we pass our uniq_id
$results = $get_load->request(); // Initial array grab
// Now to get the five minute load
echo "Five Minute Load Average is: " . $results['loadavg']['five'];
That's it. Relatively simple if you have a nice class to use. In order to get the uniq_id for a server, you would use the Server/list method.
Of course you can do this either via a web based application, or a CLI ran PHP script, for example, that might belong in a cron job (for checking load every so often for example).
Hopefully this gives a good starting point for working with the API. If you have questions, just leave a comment!
Updated as of April 2012: The class has been updated to utilize cURL and JSONTweet