Overview
Error Handling

Methods

API Documentation (API Version bleed)

Method Documentation

For each method, input parameters and output fields are listed. Input parameters are optional unless specified "Required". Output fields marked "Optional" will not always have a value, as those fields are dependent upon other conditions.

All DateTime fields are in EST/EDT unless otherwise noted in the text.

Some returned fields are themselves associative arrays with deeper structure, the details of which may not be described.

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

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

User Authorization

Many methods require user authentication to proceed. Authorization credentials are provided using HTTP Basic authentication for each request.

Authentication Tokens

Using the Account/Auth/token method, it is possible to receive a temporary authentication token. While this token remains alive, it can be used in place of a password for HTTP Basic authentication for API requests. The lifetime of each token can be specified on creation, up to a maximum of twelve hours.

Two-Factor Authentication

API method calls authenticate using the credentials of a normal user account. If the user in question has enabled two-factor authentication, each API call must be authenticated using a two-factor authentication passcode.

Each two-factor authentication passcode is valid for thirty seconds, and during that time, it is the only passcode that is valid. The trick is that, for important security reasons, each passcode can be used a maximum of one time. This necessarily means that API calls using a two-factor authentication passcode can be made a maximum of once every thirty seconds.

The workaround here is to use the Account/Auth/token method to exchange a username+password+passcode combination for a username+token. This token will allow the use of API calls without the need to submit further two-factor authentication passcodes.

Recall that an authentication token lasts, at a maximum, twelve hours, after which time a new two-factor authentication passcode would be needed to request a new token. While this could be done programmatically, such a practice would negate the security benefits of two-factor authentication (namely: the air-gap between TOTP generator and login prompt). As a result, we suggest against the enabling of two-factor authentication for user accounts which will be used to perform API requests.

Parameter Encoding

Currently the API supports the following encoding formats:

  • JSON
  • YAML

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/v1/utilities/info/ping
https://api.stormondemand.com/v1/utilities/info/ping.json