Mobile Website: Alpha | Provide Feedback

Storm on Demand Developer's Zone


Overview
Error Handling
XML Support

Methods

API Documentation (API Version 1.0)

The API is currently in Beta testing. During this period, methods might be renamed or moved, so please plan on hitting a moving target until things are solidified. Once the beta period is over, any backwards-incompatible changes will require a new version number, allowing applications to continue using the old version until they have time to upgrade.

Forming an API Request

To use the API, simply do an HTTP POST request to the url listed for the method you are attempting to access, with the request body containing a serialized parameter list (using one of the supported encodings mentioned below). The POST body should look like this (if your encoding is JSON):

{"params":{"key":"value"}}

If the response code is 200, that means we successfully processed the request. Otherwise, the appropriate apache response code will be issued. The response will either be in the format described by the method's documentation, if no error occurred, or in the following format if an exception was raised:

{"error_class":"ExceptionType","error_message":"The error message","extra_key":"extra_value"}

Each error will have at least an 'error_class' and 'error_message' returned. Depending on the error type, additional information might be passed back to help narrow down the cause of the problem. More information about exceptions can be found here

Parameter Encoding

Currently the API supports the following encoding formats:

  • JSON
  • YAML
  • XML (experimental)

If your desired encoding is not supported, feel free to request it. If it's reasonable to implement, we'll do our best to accommodate the request.

You can specify an encoding by the file extension of the API URL. If none is specified, the default (JSON) will be used. For example:

https://api.stormondemand.com/1.0/utilities/info/ping
https://api.stormondemand.com/1.0/utilities/info/ping.json
https://api.stormondemand.com/1.0/utilities/info/ping.xml

Request Metadata

Every request supports passing certain metadata along inside the POST'ed body. It would simply be another key called 'metadata' alongside the 'params' key. It can contain the following keys with their respective values:

  • ip - the original source IP of the visitor if you are using the API in a hosted application

So, if your application is hosted on a server, but you want to log the original IP address of the visitor, you can pass along their IP address (usually found in the REMOTE_ADDR environment variable) as metadata. So then, instead of the IP address of your server being logged for every request made via your application, it would log the original IP of the user. Then your request body would look like this:

JSON:

{"params":{"key":"value"},"metadata":{"ip":"127.0.0.1"}}
XML:

<?xml version="1.0" encoding="UTF-8" ?>
<request>
    <metadata>
        <ip>127.0.0.1</ip>
    </metadata>
    <params>
        <key>value</key>
    </params>
</request>

Method Documentation

Click a link on the left to view documentation for that method.