Authenticate and save a session cookie for the RightScale API 1.5 in a file called 'mycookie' (http/curl), in memory (right_api_client) or 'cookieContainer' (Powershell). Authentication is required in order to run other examples scripts (and their API calls) elsewhere in this guide.
Note: Although OAuth is preferred for production environments, the Examples section of the API guide uses standard user/pass authentication for simplicity sake.
API Endpoints
IMPORTANT! Be sure to use the correct API endpoint in accordance with your account when using the API. Available values are:
- us-3.rightscale.com
- us-4.rightscale.com
- telstra-10.rightscale.com
You can check where the account is hosted from the URL while viewing the account. Examples in these docs use a variety of endpoints as examples only. If you get a HTTP 302 redirect, you are using a different API endpoint than the account is hosted.
Curl
The following uses curl/HTTP as part of a basic Unix shell script. Because several key variables are set in the script, you can literally copy, paste and change/set the variables in accord with your cloud assets to get you on your way using the RightScale API.
Example Call
#!/bin/sh -e
email="john.doe@example.com" # The email address for your RightScale User in the Dashboard
pswd="SomeSecurePassword" # Your User's password
account="1234" # Account ID, easily obtained from navigation in the Dashboard
api_host="us-3" # Make sure to use the right API endpoint. Available values are: us-3, us-4 or telstra-10.
curl -i -H X_API_VERSION:1.5 -c mycookie -X POST --data-urlencode "email=$email" --data-urlencode "password=$pswd" -d account_href=/api/accounts/"$account" https://$api_host.rightscale.com/api/session
Sample Output
HTTP/1.1 204 No Content
Server: nginx/1.0.15
Date: Tue, 09 Oct 2012 22:11:46 GMT
Connection: keep-alive
Status: 204 No Content
X-Runtime: 64
X-Request-Uuid: 5687742b86ba40468c037d362d32a2db
Set-Cookie: rs_gbl=eNo1kEFvgjABRv9Lz5DQFmxLsoMMMzQjgJls5NIoLaJTZFBENP338bDjl3zvHd4d5MAFpxEYQHbAvYO-Uy1wCaXkYQBdABdim1FkEWtmgL2czo5FFHVQbkLkKBNChUzh5M40McQS2jNpoUmn1T9L2Iud7KDe8yw3l7gRiUcallYRCajylzZbbaU_4pK06HipN_Pv3SEL9ej3PG2HehsK0ui0SpTXQ3Eakts2O8YyDrloEjivDhjhUovIG393s_nfZq2KevyJjvFw6egpjMmnuEVfI-02wWrRnlN9HeCHxRdBlrAd53VZeWvz3W76VO6L8zJgps_fXkWuryJ5UZz7WgOXORA-Hk9qR10P; domain=.rightscale.com; path=/; HttpOnly
Set-Cookie: _session_id=e7ee4fd4bce4543a2b258b2c8d54db80; path=/; Secure; HttpOnly
Cache-Control: no-cache
Successfully authenticating with the API always result in HTTP 204. The API session cookie will be saved to the file 'mycookie'. This cookie file contains the session ID for use with subsequent API calls used by the examples. The TTL (time to live) for the session cookie is 2 hours. An example cookie file looks similar to:
$ cat mycookie # NOTE: Below cookie formatted slightly to make more readable.
# Netscape HTTP Cookie File
# http://www.netscape.com/newsref/std/cookie_spec.html
# This file was generated by libcurl! Edit at your own risk.
.rightscale.com TRUE / FALSE 0 rs_gbl eNo1kEFvgjAARv9Lz5DQFmxLsoMMMzQjgJls5WIoLaJTZFBFNP538bDjl3zvHd4d5MAFpxEYQHbAvYO-Uy1wCaXkYQBdABdim1FkEXtmgL2czo5FFHVQbkLkKBNChUzh5M40McQS2jNpoUmn1T9L2Iud7KDe8y
w3l7gRiUcallYRCajylzZbbaU_4pK06HipN_Pv3SEL9ej3PG2HehsK0ui0SpTXQ3Eakts2O8YyDrloEjivDhjh
UovIG393s_nfZq2KevyJjvFw6egpjMmnuEVfI-02wWrRnlN9HeCHxRdBlrAd53VZeWvz3W76VO6L8zJgps_
fXkWuryJ5UZz7WgOWORA-Hk9qR10P
my.rightscale.com FALSE / TRUE 0 _session_id e7ce4fb4bce4543b2b258b2c8d54db80
If your session cookie expires you will receive:
- HTTP
403 Forbidden
Session cookie is expired or invalid
message
If you get a 302 redirect, you are using a different API endpoint than the account is hosted. Use the correct API endpoint.
right_api_client
Important! Authentication works differently when using the right_api_client as opposed to the http/curl examples. Using standard authentication and the account facing RightScale API with http/curl requires authenticating whereby a session cookie is stored to a file. ('mycookie' in our examples.) The session cookie lasts for two hours, not requiring each subsequent API call to re-authenticate during that time. The authentication example below uses the right_api_client. Authentication information is stored as an object in memory. Hence, each Ruby script you develop and execute will require authenticating with the API.
Note : Technically speaking, although we refer to this simply as authentication
, its really creating an object in the Ruby language so that one can use the RightScale API.
Prerequisites
The authentication example below assumes the following Ruby and RightScale REST API client (right_api_client) installs have been completed.
Ruby
To check that Ruby version 1.8.7 or later is installed.
$ ruby -v
ruby 1.8.7 (2011-06-30 patchlevel 352) [x86_64-linux]
right_api_client
Basic installation instructions for the RightScale REST API client (right_api_client).
# sudo -i # switch to root user for installing the Ruby gem
# gem install right_api_client
Building native extensions. This could take a while...
Successfully installed json-1.7.3
Successfully installed mime-types-1.18
Successfully installed rest-client-1.6.7
Successfully installed right_api_client-1.5.9
4 gems installed
Installing ri documentation for json-1.7.3...
Installing ri documentation for mime-types-1.18...
Installing ri documentation for rest-client-1.6.7...
Installing ri documentation for right_api_client-1.5.9...
Installing RDoc documentation for json-1.7.3...
Installing RDoc documentation for mime-types-1.18...
Installing RDoc documentation for rest-client-1.6.7...
Installing RDoc documentation for right_api_client-1.5.9...
$ exit # logout from root user, create/run ruby scripts using right_api_client from a non-root user login.
Note : make sure you have the appropriate server permissions to perform these actions. For more information, see Server Login Control.
Example Call
# Script: authenticate - Establish authentication with the RS API. Requires rubygems and right_api_client.
# Authentication credentials stored in memory (not a cookie/file on local disk)
require 'rubygems'
require 'pp' # require the pp Pretty Print rubygem.
require 'right_api_client'
@client = RightApi::Client.new(:email => 'greg.doe@example.com', :password => 'SomeSecurePassword', :account_id => '1234')
puts "Available methods: #{pp @client.api_methods}" # Use pretty print for more readable output
#puts "Available methods: #{@client.api_methods}" # Use standard puts call. Less readable. Commented out so it will not be executed.
$ ruby authenticate # Run Ruby script 'authenticate' shown above.
Sample Output
Below output displays all methods available to the account that was previously authenticated. More information on each method is in the RightScale API 1.5 Online Reference.
Note : The following output uses pp
(pretty print gem) in the Ruby script, producing more readable output. Future right_api_client examples will use pp
instead of the standard Ruby puts
call (which is shown below for contrast).
["audit_entries",
"deployments",
"cloud_flow_processes",
"cloud_accounts",
"publication_lineages",
"server_templates",
"permissions",
"clouds",
"security_group_rules",
"accounts",
"tags",
"publications",
"server_arrays",
"users",
"alert_specs",
"multi_cloud_images",
"account_groups",
"servers",
"child_accounts",
"backups",
"session",
"identity_providers",
"server_template_multi_cloud_images"]
Important! Only the resources (or their sub-resources) displayed in the output above can be used by the account. See the RightScale API Online Reference documentation for all API resources. Note that the resources for your account will likely vary somewhat.
Note : Below is sample output when using a Ruby puts
call to display the available methods. The output is less readable, stringing together all methods on a single line with no delimeters or whitespace.
Available methods: audit_entriesserverscloud_flow_processescloud_accountspublication_lineagesserver_template_multi_cloud_imagespermissionsdeploymentssecurity_group_rulesaccountspublicationsserver_templatesusersbackupscloudssessionalert_specstagsaccount_groupsserver_arrayschild_accountsidentity_providersmulti_cloud_images
PowerShell
Example Call
Note : See API Endpoints section for possible values to use in $postURL
$email = "greg.doe@example.com" # Use the Email Address for your RightScale User in the Dashboard
$passwd = "SomeSecurePassword" # Your User's password
$account = "1234" # Your RightScale Account ID, easily obtained via Dashboard navigation
$postURL = "https://us-3.rightscale.com/api/session"
$stringToPost = "email=$email&password=$passwd&account_href=/api/accounts/$account"
$bytesToPost = [System.Text.Encoding]::UTF8.GetBytes($stringToPost)
$cookieContainer = New-object System.Net.CookieContainer
$webRequest = [System.Net.WebRequest]::Create($postURL)
$webRequest.Method = "POST"
$webRequest.ContentType = "application/x-www-form-urlencoded"
$webRequest.Headers.Add("X_API_VERSION","1.5")
$webRequest.ContentLength = $bytesToPost.Length
$webRequest.PreAuthenticate = $false;
$webRequest.ServicePoint.Expect100Continue = $false
$webRequest.CookieContainer = $cookieContainer
$requestStream = $webRequest.GetRequestStream()
$requestStream.Write($bytesToPost, 0, $bytesToPost.Length)
$requestStream.Close()
[System.Net.WebResponse]$response = $webRequest.GetResponse()
$responseStream = $response.GetResponseStream()
$responseStreamReader = New-Object System.IO.StreamReader -ArgumentList $responseStream
[string]$responseString = $responseStreamReader.ReadToEnd()
#this is the cookie container for subsequent requests: $cookieContainer
Sample Output
Same as http/curl response.