right_api_client 1.5.1

data/.gitignore

@@ -0,0 +1,13 @@
+.DS_Store
+nbproject
+*login.yml
+.loadpath
+.project
+.rvmrc
+.bundle
+.idea
+.idea/*
+coverage/*
+doc/*
+*~
+Gemfile.lock

data/CHANGELOG.rdoc

@@ -0,0 +1,5 @@
+= right_api_client - CHANGELOG.rdoc
+
+
+== right_api_client - 1.5.1
+Initial public release, supports all of the calls in RightScale API 1.5.

data/Gemfile

@@ -0,0 +1,3 @@
+source 'http://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2010-2011, RightScale.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,196 @@
+= RightScale API Client
+
+The right_api_client gem simplifies the use of RightScale's MultiCloud API. It provides
+a simple object model of the API resources, and handles all of the fine details involved
+in making HTTP calls and translating their responses.
+It is assumed that users are already familiar with the RightScale API:
+- API Documentation: http://support.rightscale.com/12-Guides/RightScale_API_1.5
+- API Reference Docs: http://support.rightscale.com/api1.5
+
+== Installation
+Ruby 1.9 is required.
+    gem install right_api_client
+
+== Versioning
+The right_api_client gem is versioned using the usual X.Y.Z notation, where X.Y is the
+RightScale API version, and Z is the client version. For example, if you want to use
+RightScale API 1.5, you should use the latest version of the 1.5 gem. This will ensure
+that you get the latest bug fixes for the client that is compatible with that API version.
+
+== Usage Instructions
+New users can start with the following few lines of code and navigate their way around the API by following
+the available methods. You can find your account id by logging into the RightScale dashboard (https://my.rightscale.com),
+navigate to the Settings > Account Settings page. The account is is at the end of the browser address bar.
+    require 'right_api_client'
+    @client = RightApi::Client.new(:email => 'my@email.com', :password => 'my_password', :account_id => 'my_account_id')
+    puts "Available methods: #{@client.api_methods}"
+
+The client makes working with and getting to know the API much easier. It spiders the API dynamically to
+discover its resources on the fly. At every step, the user has the ability to query api_methods(), which
+indicates the potential methods that can be called. The <tt>config/login.yml.example</tt> file provides
+details of different login parameters.
+
+=== Making API calls
+Essentially, just follow the RightScale API documentation (available from http://support.rightscale.com)
+and treat every resource in the paths as objects that can call other objects using the dot (.) operator:
+
+Examples:
+   - Index:     /api/clouds/:cloud_id/datacenters             =>  @client.clouds(:id => :cloud_id).show.datacenters.index
+   - Show:      /api/clouds/:cloud_id/datacenters/:id         =>  @client.clouds(:id => :cloud_id).show.datacenters(:id => :datacenter_id).show
+   - Create:    /api/deployments/:deployment_id/servers       =>  @client.deployments(:id => :deployment_id).show.servers.create
+   - Update:    /api/deployments/:deployment_id/servers/:id   =>  @client.deployments(:id => :deployment_id).show.servers(:id => :server_id).update
+   - Destroy:   /api/deployments/:deployment_id/servers/:id   =>  @client.deployments(:id => :deployment_id).show.servers(:id => :server_id).destroy
+   - An action: /api/servers/:server_id/launch                =>  @client.servers(:id => :server_id).show.launch
+
+As seen above, whenever you need to chain methods, you must call .show before specifying the next method.
+
+=== Parameters
+Pass-in parameters to the method that they belong to. Lets say you want to filter on the index for deployments:
+    @client.deployments.index(:filter => ['name==my_deployment'])
+The filter is the parameter for the index call and not the deployment call.
+
+=== Logging HTTP Requests
+The HTTP calls made by right_api_client can be logged in two ways:
+1. Log to a file
+    @client.log('~/right_api_client.log')
+2. Log to SDTOUT
+    @client.log(STDOUT)
+
+== Examples
+Get a list of all servers (aka doing an Index call)
+    @client.servers.index
+
+Get a list of all servers in a deployment
+    @client.deployments(:id => 'my_deployment_id').show.servers.index
+
+Get a particular server (aka doing a Show call)
+    @client.servers(:id => 'my_server_id').show
+
+Creating a server involves setting up the required parameters, then calling the create method
+    server_template_href = @client.server_templates.index(:filter => ['name==Base ServerTemplate']).first.href
+    cloud = @client.clouds(:id => 'my_cloud_id').show
+    params = { :server => {
+        :name => 'Test Server',
+        :deployment_href => @client.deployments(:id => 'my_deployment_id').show.href,
+        :instance => {
+            :server_template_href => server_template_href,
+            :cloud_href           => cloud.href,
+            :security_group_hrefs => [cloud.security_groups.index(:filter => ['name==default']).first.href],
+            :ssh_key_href         => cloud.ssh_keys.index.first.href,
+            :datacenter_href      => cloud.datacenters.index.first.href
+        }}}
+    new_server = @client.servers.create(params)
+    new_server.api_methods
+
+Launch the newly created server. Inputs are a bit tricky so they have to be set in a long string
+    inputs = "inputs[][name]=NAME1&inputs[][value]=text:VALUE1&inputs[][name]=NAME2&inputs[][value]=text:VALUE2"
+    new_server.show.launch(inputs)
+
+Run a script on the server. The API does not currently expose right_scripts, hence, the script href has
+to be retrieved from the dashboard and put in the following href format.
+    script_href = "right_script_href=/api/right_scripts/382371"
+    task = new_server.show.current_instance.show.run_executable(script_href + "&inputs[][name]=TEST_NAME&inputs[][value]=text:VALUE1")
+    task.show.api_methods
+
+Update the server's name
+    params = { :server => {:name => 'New Server Name'}}
+    @client.servers(:id => 'my_server_id').update(params)
+
+Terminate the server (i.e. shutdown its current_instance)
+    @client.servers(:id => 'my_server_id').show.terminate
+
+Destroy the server (i.e. delete it)
+    @client.servers(:id => 'my_server_id').destroy
+
+== Object Types
+The client returns 3 types of objects:
+- <b>Resources</b>: returned when you are querying a collection of resources, e.g.: <tt>client.deployments</tt>
+- <b>Resource</b>: returned when you specify an id and therefore a specific resource, e.g.: <tt>@client.deployments(:id => :deployment_id)</tt>
+  - When the content-type is type=collection then an array of Resource objects will be returned, e.g.: <tt>@client.deployments.index</tt>
+  - When the content-type is not a collection then a Resource object will be returned, e.g.: <tt>@client.deployments(:id => deployment_id).show</tt>
+- <b>ResourceDetail</b>: returned when you do a .show on a Resource, e.g.: <tt>client.deployments(:id => deployment_id).show</tt>
+<b>On all 3 types of objects you can query <tt>.api_methods</tt> to see a list of available methods, e.g.: <tt>client.deployments.api_methods</tt></b>
+
+=== Exceptions:
+- <tt>inputs.index</tt> will return an array of ResourceDetail objects since you cannot do a .show on an input
+- <tt>session.index</tt> will return a ResourceDetail object since you cannot do a .show on a session
+- <tt>tags.by_resource, tags.by_tag</tt> will return an array of ResourceDetail objects since you cannot do a .show on a resource_tag
+- <tt>monitoring_metrics(:id => :m_m_id).show.data</tt> will return a ResourceDetail object since you cannot do
+  a .show on a monitoring_metric_data
+
+== Instance Facing Calls:
+The client also supports 'instance facing calls', which use the instance_token to login.
+Unlike regular email-password logins, instance-facing-calls are limited in the amount of allowable calls.
+Since in most of the cases, the calls are scoped to the instance's cloud (or the instance itself), the cloud_id and
+the instance_id will be automatically recorded by the client, so that the user does not need to specify it.
+
+=== Examples
+    @instance_client = RightApi::Client.new(:instance_token => 'my_token', :account_id => 'my_account_id')
+    @instance_client.volume_attachments     links to /api/clouds/:cloud_id/volume_attachments
+    @instance_client.volumes_snapshots      links to /api/clouds/:cloud_id/volumes_snapshots
+    @instance_client.volumes_types          links to /api/clouds/:cloud_id/volumes_types
+    @instance_client.volumes                links to /api/clouds/:cloud_id/volumes
+    @instance_client.backups                links to /api/backups
+    @instance_client.live_tasks(:id)        links to /api/clouds/:cloud_id/instances/:instance_id/live/tasks/:id
+
+=== Notes
+For volume_attachments and volumes_snapshots you can also go through the volume:
+    @instance_client.volumes(:id => :volume_id).show.volume_attachments
+    which maps to:
+    /api/clouds/:cloud_id/volumes/:volume_id/volume_attachment
+The instance's volume_attachments can be accessed using:
+    @instance_client.get_instance.volume_attachments
+    which maps to:
+    /api/clouds/:cloud_id/instances/:instance_id/volume_attachments
+
+Because the cloud_id and the instance_id are automatically added by the client, scripts that work for regular
+email-password logins will have to be modified for instance-facing calls. The main reason behind this is the
+inability for instance-facing calls to access the clouds resource (i.e.: <tt>@instance_client.clouds(:id=> :cloud_id).show</tt> will fail)
+
+When you query <tt>api_methods</tt>, it will list all of the methods that one sees with regular email-password logins.
+Due to the limiting scope of the instance-facing calls, only a subset of these methods can be called
+(see the API Reference Docs for valid methods). If you call a method that instance's are not authorized to access,
+you will get a 403 Permission Denied error.
+
+
+= Design Decisions
+In the code, we only hard-code CRUD operations for resources. We use the .show and .index methods to make the client
+more efficient. Since it dynamically creates methods it needs to query the API at times. The .show and the .index make
+it explicit that querying needs to take place. Without them a GET would have to be queried every step of the way
+(i.e.: the index call would be client.deployments, and the create call would be client.deployments.create which would
+first do an index call).
+
+<b>In general, when a new API resource is added, you need to indicate in the client whether index, show, create, update
+and delete methods are allowed for that resource.</b>
+
+== Special Cases
+=== Returning resource_types that are not actual API resources:
+  - tags:
+    - by_resource, by_tag: both return a COLLECTION of resource_type = RESOURCE_TAG
+      - no show or index is defined for that resource_type, therefore return a collection of ResourceDetail objects
+  - data:
+    - querying .data for monitoring_metrics:
+      - no show is defined for that resource_type, therefore return a ResourceDetail object
+
+=== Index call does not act like an index call
+  - session:
+    - session.index should act like a show call and not like an index call (since you cannot query show).
+      Therefore it should return a ResourceDetail object
+  - inputs
+    - inputs.index cannot return a collection of Resource objects since .show is not allowed. Therefore it should
+      return a collection of ResourceDetail objects
+
+=== Having a resource_type that cannot be accurately determined from the URL:
+  - In server_arrays.show: resource_type = current_instance(s) (although it should be instance(s))
+  - In multi_cloud_images.show: resource_type = setting(s) (although it should be multi_cloud_image_setting)
+Put these special cases in the <tt>RightApi::Helper::INCONSISTENT_RESOURCE_TYPES</tt> hash.
+
+=== Method defined on the generic resource_type itself
+  - 'instances' => {:multi_terminate => 'do_post', :multi_run_executable => 'do_post'},
+  - 'inputs'    => {:multi_update => 'do_put'},
+  - 'tags'      => {:by_tag => 'do_post', :by_resource => 'do_post', :multi_add => 'do_post', :multi_delete =>'do_post'},
+  - 'backups'   => {:cleanup => 'do_post'}
+Put these special cases in the <tt>RightApi::Helper::RESOURCE_TYPE_SPECIAL_ACTIONS</tt> hash.
+
+=== Resources are not linked together
+  - In ResourceDetail, resource_type = Instance, need live_tasks as a method.

data/Rakefile

@@ -0,0 +1,17 @@
+require File.expand_path('../lib/right_api_client', __FILE__)
+require 'rake'
+require 'spec/rake/spectask'
+
+task :build do
+  system "gem build right_api_client.gemspec"
+end
+
+task :release => :build do
+  system "gem push right_api_client-#{RightApi::Client::VERSION}.gem"
+end
+
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = Dir.glob('spec/*_spec.rb')
+  t.spec_opts << '--format nested'
+  t.spec_opts << '--colour'
+end

data/config/login.yml.example

@@ -0,0 +1,25 @@
+# The API login details can be put in a YAML file. This is an example login.yml which
+# will be needed for login_to_client_irb.rb quick login method.
+
+# Account ID is a required parameter. You can find your account number by logging into the
+# RightScale dashboard (https://my.rightscale.com), navigate to the Settings > Account Settings page.
+# The account number is at the end of the browser address bar.
+:account_id: my_account_id
+
+# There are three login mechanisms:
+
+# 1. Use the following parameters to login with your email and password:
+:email: my@email.com
+:password: my_password
+
+# 2. Use the following parameter to login with an instance_token:
+# To find the instance_token, launch a server, navigate to the info page and under
+# User Data box, you will see RS_API_TOKEN = your_account_id:the_instance_token
+:instance_token: my_instance_token
+
+# 3. Use the following parameter to login with pre-authenticated cookies:
+:cookies: my_cookie_string
+
+# The following are optional parameters can also be set:
+:api_url: (this defaults to https://my.rightscale.com)
+:api_version: (this defaults to 1.5)

data/lib/right_api_client.rb

@@ -0,0 +1 @@
+require File.expand_path('../right_api_client/client', __FILE__)

data/lib/right_api_client/client.rb

@@ -0,0 +1,245 @@
+require 'rest_client'
+require 'json'
+require 'set'
+require 'cgi'
+
+require File.expand_path('../version', __FILE__) unless defined?(RightApi::Client::VERSION)
+require File.expand_path('../helper', __FILE__)
+require File.expand_path('../resource', __FILE__)
+require File.expand_path('../resource_detail', __FILE__)
+require File.expand_path('../resources', __FILE__)
+
+# RightApiClient has the generic get/post/delete/put calls that are used by resources
+module RightApi
+  class Client
+    include Helper
+
+    ROOT_RESOURCE = '/api/session'
+    ROOT_INSTANCE_RESOURCE = '/api/session/instance'
+    DEFAULT_API_URL = 'https://my.rightscale.com'
+
+    # permitted parameters for initializing
+    AUTH_PARAMS = %w(email password account_id api_url api_version cookies instance_token)
+    attr_reader :cookies, :instance_token
+
+    def initialize(args)
+      @api_url, @api_version = DEFAULT_API_URL, API_VERSION
+      # Initializing all instance variables from hash
+      args.each { |key,value|
+        instance_variable_set("@#{key}", value) if value && AUTH_PARAMS.include?(key.to_s)
+      } if args.is_a? Hash
+
+      raise 'This API client is only compatible with the RightScale API 1.5 and upwards.' if (Float(@api_version) < 1.5)
+      @rest_client = RestClient::Resource.new(@api_url)
+
+      # There are three options for login: credentials, instance token, or if the user already
+      # has the cookies they can just use those. See config/login.yml.example for more info.
+      @cookies ||= login()
+
+      # Add the top level links for instance_facing_calls
+      if @instance_token
+        resource_type, path, data = self.do_get(ROOT_INSTANCE_RESOURCE)
+        instance_href = get_href_from_links(data['links'])
+        cloud_href = instance_href.split('/instances')[0]
+
+        define_instance_method(:get_instance) do |*params|
+          type, instance_path, instance_data = self.do_get(ROOT_INSTANCE_RESOURCE)
+          RightApi::ResourceDetail.new(self, type, instance_path, instance_data)
+        end
+
+        Helper::INSTANCE_FACING_RESOURCES.each do |meth|
+          define_instance_method(meth) do |*args|
+            obj_path = cloud_href + '/' + meth.to_s
+            # Following are special cases that need to over-ride the obj_path
+            obj_path = '/api/backups'                if meth == :backups
+            obj_path = instance_href + '/live/tasks' if meth == :live_tasks
+            if has_id(*args)
+              obj_path = add_id_and_params_to_path(obj_path, *args)
+              RightApi::Resource.process(self, get_singular(meth), obj_path)
+            else
+              RightApi::Resources.new(self, obj_path, meth.to_s)
+            end
+          end
+        end
+      else
+        # Session is the root resource that has links to all the base resources
+        define_instance_method(:session) do |*params|
+          RightApi::Resources.new(self, ROOT_RESOURCE, 'session')
+        end
+        # Allow the base resources to be accessed directly
+        get_associated_resources(self, session.index.links, nil)
+      end
+    end
+
+    def to_s
+      "#<RightApi::Client>"
+    end
+
+    # Log HTTP calls to file (file can be STDOUT as well)
+    def log(file)
+      RestClient.log = file
+    end
+
+    # Users shouldn't need to call the following methods directly
+
+    def login
+      if @instance_token
+        params = {
+          'instance_token' => @instance_token
+        }
+        path = ROOT_INSTANCE_RESOURCE
+      else
+        params = {
+          'email'        => @email,
+          'password'     => @password,
+        }
+        path = ROOT_RESOURCE
+      end
+      params['account_href'] = "/api/accounts/#{@account_id}"
+
+      response = @rest_client[path].post(params, 'X_API_VERSION' => @api_version) do |response, request, result|
+        case response.code
+        when 302
+          response
+        else
+          response.return!(request, result)
+        end
+      end
+      response.cookies
+    end
+
+    # Returns the request headers
+    def headers
+      {'X_API_VERSION' => @api_version, :cookies => @cookies, :accept => :json}
+    end
+
+    # Generic get
+    # params are NOT read only
+    def do_get(path, params={})
+      # Resource id is a special param as it needs to be added to the path
+      path = add_id_and_params_to_path(path, params)
+
+      begin
+        # Return content type so the resulting resource object knows what kind of resource it is.
+        resource_type, body = @rest_client[path].get(headers) do |response, request, result|
+          case response.code
+          when 200
+            # Get the resource_type from the content_type, the resource_type will
+            # be used later to add relevant methods to relevant resources.
+            type = ''
+            if result.content_type.index('rightscale')
+              type = get_resource_type(result.content_type)
+            end
+
+            [type, response.body]
+          else
+            raise "Unexpected response #{response.code.to_s}, #{response.body}"
+          end
+        end
+      #Session cookie is expired or invalid
+      rescue RuntimeError => e
+        if re_login?(e)
+          @cookies = login()
+          retry
+        else
+          raise e
+        end
+      end
+
+      data = JSON.parse(body)
+      [resource_type, path, data]
+    end
+
+    # Generic post
+    def do_post(path, params={})
+      begin
+        @rest_client[path].post(params, headers) do |response, request, result|
+          case response.code
+          when 201, 202
+            # Create and return the resource
+            href = response.headers[:location]
+            relative_href = href.split(@api_url)[-1]
+            # Return the resource that was just created
+            # Determine the resource_type from the href (eg. api/clouds/id).
+            # This is based on the assumption that we can determine the resource_type without doing a do_get
+            resource_type = get_singular(relative_href.split('/')[-2])
+            RightApi::Resource.process(self, resource_type, relative_href)
+          when 200..299
+            # This is needed for the tags Resource -- which returns a 200 and has a content type
+            # therefore, ResourceDetail objects needs to be returned
+            if response.code == 200 && response.headers[:content_type].index('rightscale')
+              resource_type = get_resource_type(response.headers[:content_type])
+              data = JSON.parse(response)
+              # Resource_tag is returned after querying tags.by_resource or tags.by_tags.
+              # You cannot do a show on a resource_tag, but that is basically what we want to do
+              data.map { |obj|
+                RightApi::ResourceDetail.new(self, resource_type, path, obj)
+              }
+            else
+              response.return!(request, result)
+            end
+          else
+            raise "Unexpected response #{response.code.to_s}, #{response.body}"
+          end
+        end
+      rescue RuntimeError => e
+        if re_login?(e)
+          @cookies = login()
+          retry
+        else
+          raise e
+        end
+      end
+    end
+
+    # Generic delete
+    def do_delete(path)
+      begin
+        @rest_client[path].delete(headers) do |response|
+          case response.code
+          when 200, 204
+          else
+            raise "Unexpected response #{response.code.to_s}, #{response.body}"
+          end
+        end
+      rescue RuntimeError => e
+        if re_login?(e)
+          @cookies = login()
+          retry
+        else
+          raise e
+        end
+      end
+    end
+
+    # Generic put
+    def do_put(path, params={})
+      begin
+        @rest_client[path].put(params, headers) do |response|
+          case response.code
+          when 204
+          else
+            raise "Unexpected response #{response.code.to_s}, #{response.body}"
+          end
+        end
+      rescue RuntimeError => e
+        if re_login?(e)
+          @cookies = login()
+          retry
+        else
+          raise e
+        end
+      end
+    end
+
+    def re_login?(e)
+      e.message.index('403') && e.message =~ %r(.*Session cookie is expired or invalid)
+    end
+
+    # returns the resource_type
+    def get_resource_type(content_type)
+      content_type.scan(/\.rightscale\.(.*)\+json/)[0][0]
+    end
+  end
+end
+