Skip to end of metadata
Go to start of metadata

 

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

Video Tutorial

 

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').

Versions

  • Current Version

The Current API Version is 2.3.0 (Added 8 new methods for deployment process)

 

  • Older Versions

2.2.0 (Minor improvements and fixes)

2.1.0 (Added methods for working with apache vhosts)

2.0.0

 

Limits

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.

ScalrAPI.example.php

ScalrApiClient.java

ScalrAPI.example.pl

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:

 

Name

Description

Required

Action

Indicates the action to perform.

Example: TerminateFarm

Yes

KeyID

The KeyID for the request sender. You can get it on 'Settings -> Environments -> [Edit environment]' page

Example: 5d0e16f7498c41cc

Yes

Timestamp

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).

Example: 2009-01-07T15:04:56Z

Yes

Signature

The request signature. For more information, see "Using Query API -> Query API Authentication".

Example: Qnpl4Qk/7tINHzfXCiT7VbBatDA=

Yes

Version

The API version to use.

Example: 2.2.0

Yes

EnvID

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.

Example: 521

No
AuthVersion
Indicates auth version. You should always use: 3
Yes

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  

You can send Query requests over HTTPS only. You must include a signature in every Query request. This section describes how to create the signature.

 

  1. 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:

Query Example

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:

Select the checkbox.  Then provide a URL that will be hit whenever the selected event occurs.  The URL will be passed post parameters as follows:

event - event name
message - event description (with information about farm, role, server, etc.)

API Calls - Click for more information

ApacheVhostCreate
ApacheVhostsList
BundleTaskGetStatus
DmApplicationDeploy
DmApplicationsList
DmSourcesList
DNSZoneCreate
DNSZoneRecordAdd
DNSZoneRecordRemove
DNSZoneRecordsList
DNSZonesList
EnvironmentsList
EventsList
FarmClone
FarmGetDetails
FarmGetStats
FarmLaunch
FarmsList
FarmTerminate
GlobalVariableSet
GlobalVariablesList
LogsList
RolesList
ScriptExecute
ScriptGetDetails
ScriptsList
ServerImageCreate
ServerLaunch
ServerReboot
ServerTerminate
StatisticsGetGraphURL

Deprecated

 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)


Labels
  • None