This document contains helpful tips and tricks that are global in nature, applying to most every API 1.5 example. Although the examples in this document are Unix shell specific, the principles apply in general as well.
Table of Contents
Disclaimer: Although OAuth is preferred for production environments, the Examples section of the RightScale API Guide uses primarily standard user/pass authentication for simplicity sake.
The top of each API example provides an actionable page table of contents (TOC) that lists the specific example formats available.¹
¹ Not all examples contain all formats. Additional formats may be added in the future. Examples with more than one format include actionable "buttons" placed above the page TOC that jump to the appropriate format within the document.
RightScale's newer version of the Dashboard and API is known as "Unified Cloud Platform" (or simply UCP) while the old platform is known as "Legacy Cloud Platform." You can see if your account is a UCP account by logging into my.rightscale.com1 and if you are redirected to us-3.rightscale.com or us-4.rightscale.com, your account is a UCP account. If your account is not redirected and you remain on my.rightscale.com, you are on a LCP account. (Note: All LCP accounts will be migrated over to UCP accounts over time. For more information, please see the Endpoint URL and API redirects sections of the Unified Cloud Platform document.
1 Important! Example code in the API 1.5 Guide uses my.rightscale.com as an API endpoint. Your endpoint may vary. Be sure to use the correct API endpoint in accord with your account when using the API.
When learning and exploring using the API, the simplest way to obtain resource ID's for account, deployment, servers, etc. is simply to log into the RightScale Dashboard and navigate about gaining information of interest from the URL. For example, navigating to the Info tab of an operational server within one of your deployments, your URL will look similar to:
From this example URL you know that:
Important! Some information must be queried from the API, you cannot discover it by navigating in the Dashboard. All Cloud resource information is this way. That is, don't use the URL information when navigating to Clouds > CloudName > CloudResource (where CloudResource is any resource supported by that cloud, such as Instances, Instance Types, Security Groups, etc.) Cloud resource ID's must be obtained from the API. Either write your own API calls, or use/leverage the various examples provided in this guide. (Note: See List Deployments, List Servers, List Inputs, etc.)
Because the API is account based, not user based, you can establish multiple sessions for more than one account at a time. For example, if your RightScale User (firstname.lastname@example.org) has been invited to several accounts (such as Test with account ID 1234 and Dev with account ID 5678), you can establish a session with each account, at the same time. For example:
See the Authentication example for more information.
If you have difficulties viewing the response back directly, you will find the XML format more readable. However, if testing JSON format you can copy/paste the response and view using the following web based JSON viewing tool: http://jsonviewer.stack.hu/
Note: There are many JSON viewers freely available on the web. This one is listed as a matter of example only. Use which ever one you like the most. For example, if you have a new enough version of Python installed (2.6 or newer), you can try formatting the text based output of your shell script based on Python's JSON toolkit/library:
YourAPIscript | python -mjson.tool
Tip: Don't forget the manual pages! If not familiar with any Unix commands contained in this document, most every Unix/Linux installation includes "manual pages". For example, if interested in setting up an optional alias for the "curl" command (discussed below), yet you are unfamiliar with the alias command, try the following command to learn more: man alias
Similarly, to learn more about the "curl" command used in so many examples, type: man curl
Remember you must be authenticated first before using the API. Many might find it useful to authenticate, save the authentication cookie in a file (such as "mycookie") then setting an alias for the curl command. For example:
alias mycurl='curl -i -H X_API_VERSION:1.5 -b mycookie -X'
mycurl GET https://my.rightscale.com/api/...
Curl examples are wrapped in a basic Unix shell script which includes environment variables for specifying critical information, such as account, deployment and server numbers. Feel free to copy, paste and set environment variable values tied to your cloud assets. Its an easy entry point for using the RightScale API. For example (after authentication saved a cookie to the file "mycookie"), list all Servers within a specific Deployment:
#!/bin/sh -e DEPLOYMENT="123456789" # Set the Deployment to "12346789" curl -i -H X_API_VERSION:1.5 -b mycookie -X GET https://my.rightscale.com/api/deployments/$DEPLOYMENT/servers
You can copy, paste, and set your own value for the DEPLOYMENT variable. From there, experiment with different filters, views, etc. by manipulating the URL in accord with the API 1.5 Reference information.
By default, output is JSON. Add a ".xml" suffix to the URL in your request for XML output. Example URL:
Follow this simple trick for an easy method to switch back and forth between XML and JSON format. Don't specify either ".xml" or ".json" in your URL, rather append "$1" to the end of the URL string in your script. For example the URL from the previous example above:
Then invoke the script ('myscript') with or without a command line parameter specifying the output type you want. For example:
$ myscript # Will default to JSON output $ myscript .json # Also JSON output, explicit in the URL based on the command line parameter ($1) $ myscript .xml # Output in XML format
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.
When installing the right_api_client on Mac OSX, it also installs the rest-client gem. This gem includes "ruby extents" which is low level code written in 'C' language to interface with time-critical functions in the host OS (such as networking). The 'extent' code is compiled during installation through calls to the 'make' and 'gcc' commands from the command line by the installation package.
For this reason, installation on Mac OSX will commonly fail. The solution is to download XCode from the Apple Developer site, however this does not install the XCode Command Line Tools, which are also needed. In order to download the XCode Command Line Tools, you will need to:
Once these command line tools are downloaded and installed, the right_api_client gem should now successfully install.
There are two ways to setup logging when using the right_api_client.
When logging to a specified file, simply add a line similar to the following after creating your client object:
In the List Servers right_api_client example, placing this line after the "@client = RightApi::Client.new . . . " line results in HTTP response information being logged to the /tmp/right_api_client.log file. (Assuming you have permissions to write to the /tmp directory.) Example output after runing the List Servers script:
RestClient.get "https://my.rightscale.com/api/servers", "Accept"=>"application/json",
"Cookie"=>"_session_id=deadbeef0badf00dfeedfacec0ffee24; domain=.rightscale.com; rs_gbl=eNo1kEFvgAARBYW . . . ", "X_API_VERSION"=>"1.5" # => 200 OK | application/vnd.rightscale.server+json 254379 bytes
Note: Above output truncated and partially formatted for readability.
To log to standard output, a slightly different line of code is placed below the "@client = RightAPI . . . " call. For example:
Using Windows PowerShell is another excellent way to learn and explore using the RightScale API. Its best suited for those familiar with Windows or don't have access to a Linux box (and don't wish to spin one up in the cloud in order to get started using the RS API). In some ways its like the "Windows" equivalent of the http/curl Linux examples - Get started using the API quickly without requiring additional installations. In other ways, its a bit more like the right_api_client. Authentication is closer related to the right_api_client than http/curl, and PowerShell is a more full-featured object oriented language, unlike Unix shell scripts.
Windows PowerShell ships native to the 32-bit (x86) and 64-bit operating system from Windows 2008 and on. It can be installed on some earlier versions of Windows 2003 as well. Select one of the following in order to start Windows PowerShell.
For 64-bit Windows operating systems:
For 32-bit Windows operating systems:
Important! Although you can invoke the x86 version on a 64-bit Windows installation, when running PowerShell scripts you may receive incorrect responses and errors, including ugly timeouts. (It could appear that the API is non-responsive when actually it is fully operational.)
Note: From a PowerShell window you can also start the ISE by simply typing: ise
Authentication credentials are stored in an in-memory container for subsequent use. (Note this is different than when using http/curl which saves credentials in a cookie file.) You can include authentication explicitly within each of your PowerShell scripts. However, those learning and exploring on the fly will find this basic method helpful:
It can be helpful for troubleshooting efforts to check the value of a variable in your PowerShell script. For example, to make sure authentication related variables are "set" correctly. As a quick check, for the email setting on your Authentication script, type in the ISE bottom window:
PS C:\Users\GregD> $email@example.com
Similarly, to check your in-memory authentication container:
PS C:\Users\GregD> $cookieContainerCapacity Count MaxCookieSize PerDomainCapacity -------- ----- ------------- ----------------- 300 2 4096 20
Important! If the "Count" is zero, authentication has failed hence subsequent API invocations will fail too. In the above example, the Count correctly equals two.
Once you have a working tab you can save that as a PowerShell script. For example, save your Authentication, List Clouds, etc. as scripts so you can use them again without having to determine account numbers, deployment ID's, ... Simply click the disk icon in the upper left and save the .ps1 file with a descriptive name.
Important! If you do save PowerShell scripts to your local drive and then try to run them, you will receive a security related error similar to the following:
PS C:\Users\GregDoe> C:\Users\GregDoe\...\RS API PowerShell\Auth.ps1 File C:\Users\GregDoe\...\RS API PowerShell\Auth.ps1 cannot be loaded because the execution of scripts is disabled on this system. Please see "get-help about_signing" for more details. At line:0 char:0
Issue the "get-help about_signing" command from your PowerShell window which details how to set privileges such that you can run your script one time, many times, etc.
Note: As a work-around, you can simply copy/paste the contents of your script into a new tab (^N) and execute that.
Some may find PowerGUI a helpful interface and script editor for PowerShell. Its a free download and simple to install. One handy feature that developers like is the right hand pane displays variable information.
Postman is a free Google Chrome browser plugin. This is the easiest way to get started learning the RightScale API, especially suited for those with little to no development experience, who are more "visual" learners. With Postman, a basic understanding of the RightScale platform and the online reference documentation you can get started using our API! All you need to know to get started is in Appendix A - APEye Tools > Google Chrome Postman Plugin of this guide.
Although HTTP errors are not specific to a specific operating system or API format, most of the following are more likely to occur when running under Linux... hence that is the context provided in the examples.
Wrong cloud! Don't forget, API 1.5 supports non EC2 clouds only! If trying to query cloud assets in AWS EC2 you will get a response similar to:
HTTP/1.1 422 Unprocessable Entity . . . UnsupportedResource: The current api version does not support resources belonging to aws cloud
When authenticating, if using a shell script with a basic variable for your user password and it includes a "$" it will get interpreted by the shell and produce undesired results (HTTP 401 Unauthorized). However, you can escape the meaning of the "$" by preceding it with a "\". For example, if your password is literally "John$Doe":
PASS="John$Doe" # Will fail later in the script when trying to authenticate via your curl command PASS="John\$Doe" # Will work in subsequent curl command when using variable substitution for $PASS.
Although a HTTP 500 Internal Server error can mean many things, some of which requiring reaching Support at RightScale.com, there is a benign circumstance that is easily remedied that can result in this error. For example, similar to the Unauthorized section above, a "$%" sign in your password will cause this error as the variable substitution in the shell thinks you are attempting to work with job control (background/foreground jobs). You can attempt to fix this by preceding both characters with a "\" (e.g. "\$\%") or making sure the special characters are not run together. (Note: Password generators can run these characters together, resulting with the HTTP 500 error if the password is not changed or characters escaped correctly.)
"Permission Denied" when running a script means it does not have executable permissions set on the file. When creating various scripts to run against the API, its common to forget to set the script so it is executable. If its not executable you will receive a "Permission denied" message. For example, use the change mode (chmod) command to configure proper permissions before you run a Unix shell script named 'myscript':
chmod 755 myscript
Then re-run your script and it should execute fine. (Note: The command "ls -l" shows a long listing of all files in the current directory. A long listing includes (r)ead, (w)rite and e(x)ecute permissions for the owner, group and world (everybody else) on each file.)
Tip: The above chmod command uses a binary format to set the permissions on the 'myscript' file so it is executable. Some may prefer to use a different format. For example: $ chmod +x myscript To learn more about chmod: $ man chmod
Another common mistake is trying to run your script when the current directory is not in your executable path. If the command "echo $PATH" does not show a "." in it you need to either add it or run your script and include the current directly implicitly. For example:
© 2006-2014 RightScale, Inc. All rights reserved.
RightScale is a registered trademark of RightScale, Inc. All other products and services may be trademarks or servicemarks of their respective owners.