- Get started with the API
- Video Tutorial
- Sample libraries & helper scripts
- How to use the API with several environments
- Common Request Parameters
- Using the Query API
- API Calls - Click for more information
For the programmers among you, Scalr has an API that allows you to execute commands on your infrastructure.
For example launching or terminating Instances, getting details for one of your Farms, or listing DNS information.
Get started with the API
To use the API, you must enable it for each Environment (from the menu, Settings > Manage Environments, then Options > Edit from the relevant Environment like 'default').
The Current API Version is 2.3.0 (Added 8 new methods for deployment process)
2.2.0 (Minor improvements and fixes)
2.1.0 (Added methods for working with apache vhosts)
By default, each user is limited to 10,000 requests per hour for a single environment.
If you need this value to be increased, please contact our support.
Sample libraries & helper scripts
Attached to this page are some sample scripts (PHP, Java, and Perl) for using Scalr's API. Download and modify them to get started easily.
How to use the API with several environments
- In your terminal:
Scalr tool allows you to execute the following command to retrieve all your environments and their ID:
Replace ENV_ID with the ID you got before, "scalr configure" command will save it for your next commands:
- In the code:
You can get your environment IDs with EnvironmentsList Action, if you don't have Scalr tool installed.
Common Request Parameters
All Query operations share a set of common parameters that must be present in each call:
Indicates the action to perform.
The KeyID for the request sender. You can get it on 'Settings -> Environments -> [Edit environment]' page
The date and time at which the request is signed, in the format YYYY-MM-DDThh:mm:ssZ. For more information, go to ISO 8601 (http://www.w3.org/TR/NOTE-datetime).
The request signature. For more information, see "Using Query API -> Query API Authentication".
The API version to use.
Environment id to perform action within. To be used when a user has access more than to one Environment. If omitted, first Environment is assumed.
Indicates auth version. You should always use: 3
Using the Query API
The Request ID
In every response from Scalr, you will find a string element called TransactionID. This is simply a unique identifier Scalr assigns to this request for tracking and troubleshooting purposes.
Query API Authentication
- Create string to sign in the following format:
2. Calculate an RFC 2104-compliant HMAC with the string you just created, your API Access Key (You can get it on 'Settings -> System settings' page) as the key, and SHA256 as the hash algorithm.For more information, go to http://www.ietf.org/rfc/rfc2104.txt.
3. Convert the Resulting value to base64.
4. Use the Resulting value as the value of the Signature request parameter.
The final signature you send in the request must be URL encoded as specified in RFC 3986 (for more information, go to http://www.ietf.org/rfc/rfc3986.txt). If your toolkit URL encodes your final request, then it handles the required URL encoding of the signature. If your toolkit doesn't URL encode the final request, then make sure to URL encode the signature before you include it in the request. Most importantly, make sure the signature is URL encoded only once. A common mistake is to URL encode it manually during signature formation, and then again when the toolkit URL encodes the entire request.
Do not forget to add the following argument into your request:
LaunchFarm API Request
Following is the string to sign:
Following is the signed request:
Configuring Events and Notifications
In the Events and Notifications configuration under Farms, you can configure either email alerts or callbacks to a web URL to be notified about any of the listed events (like HostUp, HostDown, IPAddressChanged etc).
MailEventObserver observer settings:Select the email checkbox and provide a mail address to be notified. Select all the events that you want to be notified about.
RESTEventObserver observer setting:
event - event name
message - event description (with information about farm, role, server, etc.)
API Calls - Click for more information
Please be mindful that the Scalr 1.X API is not compatible with later versions. This page is provided to help existing installations of Scalr.
2010-02-25 (added GetStatisticsGraphURL method)
2009-10-06 (contains minor improvements and various bugfixes)
2009-08-14 (added GetEvents, GetLogs, GetScriptDetails, RebootInstance methods. Added an ability to execute script with specified revision and arguments)
2009-08-04 (added the ListDNSZones, AddDNSZoneRecord, RemoveDNSZoneRecord, ListDNSZoneRecords methods)
2009-07-07 (added the TerminateInstance, LaunchInstance, GetFarmDetails methods)