right_api_client 1.5.9 → 1.5.12

data/.gitignore

@@ -10,4 +10,3 @@ nbproject
 coverage/*
 doc/*
 *~
-Gemfile.lock

data/{CHANGELOG.rdoc → CHANGELOG.md}

@@ -1,4 +1,17 @@
-= right_api_client - CHANGELOG.rdoc
+= right_api_client - CHANGELOG.md
+
+== right_api_client - 1.5.11
+#33 fix specs and readme
+#32 fix nested array of hashes params
+#30 README markdown formatting
+#29 rename read me and add mandatory ownership string
+
+== right_api_client - 1.5.10
+#28 Preserve the last request made and make it accessible
+#26 Fix specs. Separate out unit tests and functional tests.
+#25 Add support for other RightScale endpoints.
+#23 Fix child_account update href.
+#20 Always store the latest cookies. Also includes a jump from rspec 1.3.0 to 2.9.0 and spec infrastructure reorganization.
 
 == right_api_client - 1.5.9
 Downgrade even further to Ruby 1.8.7. Should still work in Ruby 1.9.x.

data/Gemfile

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

data/{README.rdoc → README.md}

@@ -1,40 +1,46 @@
-= RightScale API Client
+# RightScale API Client
 
-The right_api_client gem simplifies the use of RightScale's MultiCloud API. It provides
+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
+  - API Documentation: http://support.rightscale.com/12-Guides/RightScale_API_1.5
+  - API Reference Docs: http://reference.rightscale.com/api1.5
+
+Maintained by the RightScale "Yellow_team" 
+
+## Installation
 Ruby 1.8.7 or higher 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
+## 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
+## 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
+indicates the potential methods that can be called. The ```config/login.yml.example``` file provides
 details of different login parameters.
 
-=== Making API calls
+### 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
@@ -44,29 +50,38 @@ Examples:
 
 As seen above, whenever you need to chain methods, you must call .show before specifying the next method.
 
-=== Parameters
+### 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:
+### 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
+
+2. Log to STDOUT
+
     @client.log(STDOUT)
 
-== Examples
+## 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 => {
@@ -83,48 +98,56 @@ Creating a server involves setting up the required parameters, then calling the
     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
+## 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
+
+- <b>Resources</b>: returned when you are querying a collection of resources, e.g.: ```client.deployments```
+- <b>Resource</b>: returned when you specify an id and therefore a specific resource, e.g.: ```@client.deployments(:id => :deployment_id)```
+  - When the content-type is type=collection then an array of Resource objects will be returned, e.g.: ```@client.deployments.index```
+  - When the content-type is not a collection then a Resource object will be returned, e.g.: ```@client.deployments(:id => deployment_id).show```
+- <b>ResourceDetail</b>: returned when you do a .show on a Resource, e.g.: ```client.deployments(:id => deployment_id).show```
+
+ <b>On all 3 types of objects you can query ```.api_methods``` to see a list of available methods, e.g.: ```client.deployments.api_methods```</b>
+
+### Exceptions:
+- ```inputs.index``` will return an array of ResourceDetail objects since you cannot do a .show on an input
+- ```session.index``` will return a ResourceDetail object since you cannot do a .show on a session
+- ```tags.by_resource, tags.by_tag``` will return an array of ResourceDetail objects since you cannot do a .show on a resource_tag
+- ```monitoring_metrics(:id => :m_m_id).show.data``` 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.
+## 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
+### 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
@@ -133,27 +156,30 @@ the instance_id will be automatically recorded by the client, so that the user d
     @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:
+### 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:
+
+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
+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)
+inability for instance-facing calls to access the clouds resource (i.e.: ```@instance_client.clouds(:id=> :cloud_id).show``` will fail)
 
-When you query <tt>api_methods</tt>, it will list all of the methods that one sees with regular email-password logins.
+When you query ```api_methods```, 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
+# 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
@@ -163,16 +189,16 @@ 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:
+## 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
+    - 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
+    - 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
+### 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
@@ -180,23 +206,36 @@ and delete methods are allowed for that resource.</b>
     - 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.
+### 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 ```RightApi::Helper::INCONSISTENT_RESOURCE_TYPES``` 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 ```RightApi::Helper::RESOURCE_TYPE_SPECIAL_ACTIONS``` hash.
+
+### Resources are not linked together
+  - In ResourceDetail, resource\_type = Instance, need live\_tasks as a method.
+
+
+# Testing
+
+## Unit Testing
+bundle exec rspec spec/unit
 
-=== 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.
+## Functional Testing
+See Usage Instructions for how to configure functional testing.
 
-=== Resources are not linked together
-  - In ResourceDetail, resource_type = Instance, need live_tasks as a method.
+bundle exec rspec spec/functional
 
-= Troubleshooting
+# Troubleshooting
 
-== Wrong ruby version
+## Wrong ruby version
 
 Ruby 1.8.7 or higher is required.

data/config/login.yml.example

@@ -6,9 +6,14 @@
 # The account number is at the end of the browser address bar.
 :account_id: my_account_id
 
-# There are three login mechanisms:
+# There are four login mechanisms:
 
-# 1. Use the following parameters to login with your email and password:
+# 0. Use the following parameters to login with your email and base64-encoded password:
+# To encode your plaintext password, use 'base64' command or similar.
+:email: my@email.com
+:password_base64: my_password_encoded_as_base64
+
+# 1. Use the following parameters to login with your email and plaintext password:
 :email: my@email.com
 :password: my_password
 
@@ -20,6 +25,6 @@
 # 3. Use the following parameter to login with pre-authenticated cookies:
 :cookies: my_cookie_string
 
-# The following are optional parameters can also be set:
+# The following are optional parameters:
 :api_url: (this defaults to https://my.rightscale.com)
-:api_version: (this defaults to 1.5)
+:api_version: (this defaults to 1.5)

data/lib/right_api_client/client.rb

@@ -2,13 +2,14 @@ require 'rest_client'
 require 'json'
 require 'set'
 require 'cgi'
+require 'base64'
 
 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__)
-require File.expand_path('../exceptions', __FILE__)
+require File.expand_path('../errors', __FILE__)
 
 # RightApiClient has the generic get/post/delete/put calls that are used by resources
 module RightApi
@@ -20,23 +21,35 @@ module RightApi
     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
+    AUTH_PARAMS = %w[
+      email password_base64 password account_id api_url api_version
+      cookies instance_token
+    ]
+
+    attr_reader :cookies, :instance_token, :last_request
 
     def initialize(args)
+
       raise 'This API client is only compatible with Ruby 1.8.7 and upwards.' if (RUBY_VERSION < '1.8.7')
+
       @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, :timeout => -1)
+      @last_request = {}
+
+      # 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.
+      login() unless @cookies
 
-      # 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()
+      timestamp_cookies
 
       # Add the top level links for instance_facing_calls
       if @instance_token
@@ -82,32 +95,48 @@ module RightApi
       RestClient.log = file
     end
 
-    # Users shouldn't need to call the following methods directly
+    # Given a path returns a RightApiClient::Resource instance.
+    #
+    def resource(path)
+
+      r = Resource.process(self, *do_get(path))
+
+      r.respond_to?(:show) ? r.show : r
+    end
+
+    # Seems #resource tends to expand (call index) on Resources instances,
+    # so this is a workaround.
+    #
+    def resources(type, path)
+
+      Resources.new(self, path, type)
+    end
+
+    protected
 
     def login
-      if @instance_token
-        params = {
-          'instance_token' => @instance_token
-        }
-        path = ROOT_INSTANCE_RESOURCE
+      params, path = if @instance_token
+        [ { 'instance_token' => @instance_token },
+          ROOT_INSTANCE_RESOURCE ]
+      elsif @password_base64
+        [ { 'email' => @email, 'password' => Base64.decode64(@password_base64) },
+          ROOT_RESOURCE ]
       else
-        params = {
-          'email'        => @email,
-          'password'     => @password,
-        }
-        path = ROOT_RESOURCE
+        [ { 'email' => @email, 'password' => @password },
+          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
+      response = @rest_client[path].post(params, 'X_API_VERSION' => @api_version) do |response, request, result, &block|
+        if response.code == 302
+          update_api_url(response)
+          response.follow_redirection(request, result, &block)
         else
           response.return!(request, result)
         end
       end
-      response.cookies
+
+      update_cookies(response)
     end
 
     # Returns the request headers
@@ -115,39 +144,57 @@ module RightApi
       {'X_API_VERSION' => @api_version, :cookies => @cookies, :accept => :json}
     end
 
+    def update_last_request(request, response)
+      @last_request[:request]  = request
+      @last_request[:response] = response
+    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)
 
+      req, res = nil
+
       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|
+        resource_type, body = @rest_client[path].get(headers) do |response, request, result, &block|
+          req, res = request, response
+          update_cookies(response)
+          update_last_request(request, response)
+
           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)
+            # 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')
+              get_resource_type(result.content_type)
+            else
+              ''
             end
 
             [type, response.body]
+          when 301, 302
+            update_api_url(response)
+            response.follow_redirection(request, result, &block)
           when 404
-            raise Exceptions::UnknownRouteException.new("HTTP Code: #{response.code.to_s}, Response body: #{response.body}")
+            raise UnknownRouteError.new(request, response)
           else
-            raise Exceptions::ApiException.new("HTTP Code: #{response.code.to_s}, Response body: #{response.body}")
+            raise ApiError.new(request, response)
           end
         end
-      rescue Exceptions::ApiException => e
+      rescue ApiError => e
         if re_login?(e)
-          #Session cookie is expired or invalid
-          @cookies = login()
+          # session cookie is expired or invalid
+          login()
           retry
         else
-          raise e
+          raise wrap(e, :get, path, params, req, res)
         end
+      rescue => e
+        raise wrap(e, :get, path, params, req, res)
       end
 
       data = if resource_type == 'text'
@@ -161,8 +208,16 @@ module RightApi
 
     # Generic post
     def do_post(path, params={})
+      params = fix_array_of_hashes(params)
+
+      req, res = nil
+
       begin
         @rest_client[path].post(params, headers) do |response, request, result|
+          req, res = request, response
+          update_cookies(response)
+          update_last_request(request, response)
+
           case response.code
           when 201, 202
             # Create and return the resource
@@ -173,6 +228,8 @@ module RightApi
             # 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 204
+            nil
           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
@@ -188,62 +245,89 @@ module RightApi
               response.return!(request, result)
             end
           when 404
-            raise Exceptions::UnknownRouteException.new("HTTP Code: #{response.code.to_s}, Response body: #{response.body}")
+            raise UnknownRouteError.new(request, response)
           else
-            raise Exceptions::ApiException.new("HTTP Code: #{response.code.to_s}, Response body: #{response.body}")
+            raise ApiError.new(request, response)
           end
         end
-      rescue Exceptions::ApiException => e
+
+      rescue ApiError => e
         if re_login?(e)
-          @cookies = login()
+          login()
           retry
         else
-          raise e
+          raise wrap(e, :post, path, params, req, res)
         end
+      rescue => e
+        raise wrap(e, :post, path, params, req, res)
       end
     end
 
     # Generic delete
-    def do_delete(path)
+    def do_delete(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)
+
+      req, res = nil
+
       begin
         @rest_client[path].delete(headers) do |response, request, result|
+          req, res = request, response
+          update_cookies(response)
+          update_last_request(request, response)
+
           case response.code
-          when 200, 204
+          when 200
+          when 204
+            nil
           when 404
-            raise Exceptions::UnknownRouteException.new("HTTP Code: #{response.code.to_s}, Response body: #{response.body}")
+            raise UnknownRouteError.new(request, response)
           else
-            raise Exceptions::ApiException.new("HTTP Code: #{response.code.to_s}, Response body: #{response.body}")
+            raise ApiError.new(request, response)
           end
         end
-      rescue Exceptions::ApiException => e
+      rescue ApiError => e
         if re_login?(e)
-          @cookies = login()
+          login()
           retry
         else
-          raise e
+          raise wrap(e, :delete, path, params, req, res)
         end
+      rescue => e
+        raise wrap(e, :delete, path, params, req, res)
       end
     end
 
     # Generic put
     def do_put(path, params={})
+      params = fix_array_of_hashes(params)
+
+      req, res = nil
+
       begin
         @rest_client[path].put(params, headers) do |response, request, result|
+          req, res = request, response
+          update_cookies(response)
+          update_last_request(request, response)
+
           case response.code
           when 204
+            nil
           when 404
-            raise Exceptions::UnknownRouteException.new("HTTP Code: #{response.code.to_s}, Response body: #{response.body}")
+            raise UnknownRouteError.new(request, response)
           else
-            raise Exceptions::ApiException.new("HTTP Code: #{response.code.to_s}, Response body: #{response.body}")
+            raise ApiError.new(request, response)
           end
         end
-      rescue Exceptions::ApiException => e
+      rescue ApiError => e
         if re_login?(e)
-          @cookies = login()
+          login()
           retry
         else
-          raise e
+          raise wrap(e, :put, path, params, req, res)
         end
+      rescue => e
+        raise wrap(e, :put, path, params, req, res)
       end
     end
 
@@ -255,6 +339,67 @@ module RightApi
     def get_resource_type(content_type)
       content_type.scan(/\.rightscale\.(.*)\+json/)[0][0]
     end
+
+    # Makes sure the @cookies have a timestamp.
+    #
+    def timestamp_cookies
+
+      return unless @cookies
+
+      class << @cookies; attr_accessor :timestamp; end
+      @cookies.timestamp = Time.now
+    end
+
+    # Sets the @cookies (and timestamp it).
+    #
+    def update_cookies(response)
+
+      return unless response.cookies
+
+      (@cookies ||= {}).merge!(response.cookies)
+      timestamp_cookies
+    end
+
+    #
+    # A helper class for error details
+    #
+    class ErrorDetails
+
+      attr_reader :method, :path, :params, :request, :response
+
+      def initialize(me, pt, ps, rq, rs)
+
+        @method = me
+        @path = pt
+        @params = ps
+        @request = rq
+        @response = rs
+      end
+
+      def code
+
+        @response ? @response.code : nil
+      end
+    end
+
+    # Adds details (path, params) to an error. Returns the error.
+    #
+    def wrap(error, method, path, params, request, response)
+
+      class << error; attr_accessor :_details; end
+      error._details = ErrorDetails.new(method, path, params, request, response)
+
+      error
+    end
+
+    private
+
+    def update_api_url(response)
+      # Update the rest client url if we are redirected to another endpoint
+      uri = URI.parse(response.headers[:location])
+      @api_url = "#{uri.scheme}://#{uri.host}"
+      @rest_client = RestClient::Resource.new(@api_url, :timeout => -1)
+    end
   end
 end