We continue to expand support for both cloud infrastructure as well as RightScale functionality. If you have suggestions for how the API could better serve you, please contact us at support@rightscale.com. For further API information and examples, we encourage you to visit the RightScale Forums at https://forums.rightscale.com/.

Introduction

The RightScale API follows REST conventions as much as possible. It provides administrative and information gathering capabilities based on the client's view of the RightScale Dashboard.

Resources and URLs

Each resource that the API exports is fully referenced by a fixed URL. Account-based resources will use the following URL format:

• Single Resources
  https://my.rightscale.com/api/acct/account_id/resource/resource_id?parameters
  Single resource URLs always end with the resource name (in plural) followed by its resource id. Querying a resource always returns a single object of the resource type. For example, querying /api/acct/99/deployments/100 returns deployment type contents.
   

• Resource Collection
  https://my.rightscale.com/api/acct/account_id/resource?parameters
  Collection URLs always end with the resource name (in plural) and not with an id. Querying a collection URL will always return a list of objects of the resource type. For example, querying /api/acct/99/deployments returns a collection of deployment type resources.

 

The API uses the following standard HTTP methods for interacting with a resource:

• POST - used for creating a new resource
• GET - used for listing a collection of resources or showing a single resource
• PUT - used for updating a resource
• DELETE - used for deleting a resource

Note: GET never modifies resources or performs actions.

 

 

API Versioning

The API uses a major.minor version number system. Non backwards compatible changes cause a major version number change. Minor number changes reflect backwards compatible changes or bug fixes that are not deemed to be features.

The RightScale public API has versioning support for all API calls. Every single API call must specify the API version to invoke, and API calls with no specified version will fail. The API version consists of a major and a minor number, such as 1.0.

There are two different ways with which a client accessing the API can use to specify the version:

1. Preferred Method: using an X-API-VERSION HTTP header, e.g., X-API-VERSION: 1.0
2. Alternate Method: using a api_version parameter in the query string of the request, e.g., /api/acct/99/servers?api_version=1.0

The rationale for using a header as opposed to a popular alternative, which is to embed the version into the URI like /api/v1_0/... is that we'd like the URIs of resources not to change with API version changes. So /api/server/55 refers to the same resource whether it's v1 or v2, but the representation of this resource and the operations available on it may differ.

 

 

API Authentication

All API calls MUST occur over SSL (HTTPS) and all API calls must be authenticated to a user. In RightScale, a user can belong to many accounts, however the authentication is done only at the user level. Once the user is authenticated, he or she will have access to all accounts it belongs to (provided that the account has api_access enabled). Which account to use in each API call will be specified outside the context of authentication (i.e., it will be done as an incoming parameter).

The 'login' call requires basic HTTP authentication using the same credentials as used when accessing the web site. For regular API usage it is recommended you create a separate user for API access to enable auditing and to isolate the API clients from password changes.  That is, to protect API access from failing after a simple RightScale user password change.  All other API calls must use cookie-based authentication using the cookies returned by the 'login' call.

Response Formats

RightScale API supports two different output types: XML and JSON. To instruct the API calls to return the desired format, the client can use 'xml' or 'js' formats. When no format is specified, it will default to XML.

There are two different but equivalent ways to specify the format:

1. Including a "format" parameter in the URL query. For example, this URL /api/acct/99/servers?api_version=1.0&format=js will request a JSON formatted list of servers for account 99.
2. Terminating the URL path (not the query string) with the format extension. For example, to retrieve the same list of servers as above in xml format, we could use: /api/acct/99/servers.xml?api_version=1.0

 

 

Resource Locations and References

Each resource returned by the API will always include an 'href' attribute, specifying the full URL referencing itself. In addition to containing its own reference, most resources will also have references to other resources. E.g. a server belongs to a deployment, a server array has many servers, etc. These references to other resources will be presented in the responses using a resource-href format, which will contain the full URL reference to the related resource. For example, response for server 100 might look like:

<server type="Server">
  <nickname>testing</nickname>
  <href>http://localhost:3000/api/acct/99/servers/100</href>
  <deployment-href>https://my.rightscale.com/api/acct/99/deployments/3</deployment-href>
  ...
</server>

In this example, we can retrieve the deployment that the server belongs to, by following the 'deployment-href' URL.

Every exported resource will always contain the 'href' attribute, along with the list of direct attributes (i.e., nickname, created-at,...), and the list of hrefs it's related to. In the future, it will be possible to instruct the API call to include the complete related resource within the response body, rather than only its href (future enhancement).

 

 

Collections

When querying a collection the API will support a sophisticated set of filtering, sorting, and inclusion of sub-resources. The first version of the API is limited to simple filtering in that respect, but the syntax is prepared to be upwards compatible.

Collection queries always return a list of objects of the resource type. For example, querying /api/acct/99/servers returns a collection of server type resources. For example:

<servers type="array">
  <server type="Server">
    <created-at type="datetime">2007-12-08T00:09:55Z</created-at>
    <nickname>FrontEnd</nickname>
    <updated-at type="datetime">2008-08-26T01:15:45Z</updated-at>
    <href>https://my.rightscale.com/api/acct/99/servers/93</href>
    <deployment-href>https://my.rightscale.com/api/acct/99/deployments/4</deployment-href>
    <state>stopped</state>
    <server-type>ec2</server-type>
  </server>
  <server type="Server">
    <created-at type="datetime">2007-12-10T19:49:44Z</created-at>
    <nickname>Database</nickname>
    <updated-at type="datetime">2008-04-29T16:56:52Z</updated-at>
    <href>https://my.rightscale.com/api/acct/99/servers/97</href>
    <deployment-href>https://my.rightscale.com/api/acct/99/deployments/3</deployment-href>
    <state>stopped</state>
  <server-type>ec2</server-type>
  </server>
  ...
</servers>

The result set of a collection query may be narrowed-down by filtering using the "filter" parameter. For example, we can retrieve the list of servers that have "FrontEnd" nicknames by issuing /api/acct/99/servers?filter%3Dnickname%3DFrontEnd (i.e., encoding for filter=nickname=FrontEnd)

<servers type="array">
  <server type="Server">
    <created-at type="datetime">2007-12-08T00:09:55Z</created-at>
    <nickname>FrontEnd</nickname>
    <updated-at type="datetime">2008-08-26T01:15:45Z</updated-at>
    <href>https://my.rightscale.com/api/acct/99/servers/93</href>
    <deployment-href>https://my.rightscale.com/api/acct/99/deployments/4</deployment-href>
    <state>stopped</state>
    <server-type>ec2</server-type>
  </server>
</servers>

It is also possible to filter by related resource, by using the attributes of "-href" attributes directly. For example, we can get the collection of all servers belonging to deployment https://my.rightscale.com/api/acct/99/deployments/4, by issuing /api/acct/99/servers?filter=deployment_href%3Dhttps%3A%2F%2Fmy.rightscale.com%2Fapi%2Facct%2F99%2Fdeployments%2F3 (i.e., encoding for filter=deployment_href=https://my.rightscale.com/api/acct/99/deployments/3):

<servers type="array">
  <server type="Server">
    <created-at type="datetime">2007-12-10T19:49:44Z</created-at>
    <nickname>Database</nickname>
    <updated-at type="datetime">2008-04-29T16:56:52Z</updated-at>
    <href>https://my.rightscale.com/api/acct/99/servers/97</href>
    <deployment-href>https://my.rightscale.com/api/acct/99/deployments/3</deployment-href>
    <state>stopped</state>
  <server-type>ec2</server-type>
  </server>
  <server type="Server">
    <created-at type="datetime">2008-02-08T00:04:55Z</created-at>
    <nickname>Backup</nickname>
    <updated-at type="datetime">2008-07-26T01:12:45Z</updated-at>
    <href>https://my.rightscale.com/api/acct/99/servers/93</href>
    <deployment-href>https://my.rightscale.com/api/acct/99/deployments/3</deployment-href>
    <state>stopped</state>
    <server-type>ec2</server-type>
  </server>
  ...
</servers>

Our intent is to support a small query language in future API versions such that it is possible to express conditions like "deployment equals <Name> and state is not running." In API version 1.0, only 'attribute = value' is supported, where attribute is the exact attribute name exported in the resource.