Overview

Once you have learned about the RightScale API and know how to look things up (Reference section), seeing practical examples can help solidify precisely how to construct calls for various API Resources. Examples bring the learning experience full circle. Each example provided pertains to an often used API Resource. Each example includes a curl (bash/sh) example and often a Ruby (right_api_client) example.1

API examples are really designed to be used in parallel with the API 1.5 online reference information. We strongly recommend you use the online reference information at all phases of your learning curve.

1 The Examples section is a work in progress. It is our plan to not only add to the number of examples, but to add to the curl examples with a REST API client (right_api_client) examples. The curl examples have the advantage of ease of use when exploring, whereas the REST API client is likely preferred by more seasoned developers. Although Ruby experience is helpful, the right_api_client examples do their best to minimize the complexity of Ruby used. Some examples also contain a Supplemental section. (Usually this includes a filter or view.)

Error Handling

Error handling was completely revamped in version 1.5 and returns a detailed error message stating exactly why a request failed (i.e. parameter missing errors, resource invalid errors, cloud errors etc.). The response body will include a descriptive error message to assist you with debugging efforts, except in the event of a 500 Internal Server Error.

HTTP Error Code Description
301 Moved Permanently An error code that indicates that the URL has been redirected to another URL. The location for the URL will be listed in the response.
400 Bad Request Parameter or filter errors, e.g. missing a required parameter. The request should not be repeated without modifying it.
401 Unauthorized Authentication errors, e.g. wrong username/password or wrong instance token (for instance facing sessions).
403 Forbidden Authorization errors, e.g. Not having sufficient user 'roles' to perform a particular action or the account might not have the required setting. This error code can also be returned with a Session cookie is expired or invalid message indicating that the session has expired.
404 Not Found Unknown routes, e.g. making a GET request to /api/unknown_route.
405 Method Not Allowed Method not allowed errors, e.g. making a DELETE request to /api/clouds.
406 Not Acceptable Unknown format error, e.g. making a GET request to /api/clouds.PDF.
422 Unprocessable Entity A generic error code that indicates: resource not found (e.g. GET /api/clouds/unknown_cloud), invalid resource (e.g. an error occurred during resource creation), invalid API version (e.g. setting X_API_VERSION to 0.9), or cloud errors (e.g. trying to attach a volume to a device that is already taken).
500 Internal Server Error Unknown errors, please contact support if you get this error.
504 Gateway Timed Out The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI (e.g. HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed to access in attempting to complete the request.

Note: To implementors: some deployed proxies are known to return 400 or 500 when DNS lookups time out.

See also

  • RightScale right_api_client (On github) - Developed by RightScale engineering
  • RightScale API 1.5 PHP library (On github) - This PHP library is under construction, but has many helpful examples that PHP developers will find useful. Skilled developers may find the github examples more compelling than the Examples section of this guide.
  • RSC - A Generic RightScale API Client (On github) - Provides both a command line tool and a go package for interacting with the RightScale APIs. Developed by RightScale engineering.