softlayer_api 2.1.0 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ec9821bee592ef106f6fd3cc00af8c1b980766a8
-  data.tar.gz: 3bda1cb83614eb4a8876a96aaad86d3104825ddb
+  metadata.gz: 390f9ff4017222664251b8ccf219c01fe051f936
+  data.tar.gz: 7f3bd11e1d5915e3bbe5c1a47602543fa86768a7
 SHA512:
-  metadata.gz: b885072f2075801dc2f0a5dddb3ca0f902c560522d4cd2b9c7fb87f51761242a197fdd8c550a6a3ef2f10dabe6fb6c6fe8433964271f653a4c7afaac4b7618e5
-  data.tar.gz: 5c182f1f9633948a8b94bc7824f383434e23f468a9eb3a849b719849f56cbafda0af793a0c9e95fbfeca166b1f676da94963b1d3f7b8eaa9c3541daeb6d3f74a
+  metadata.gz: 204a913bcc8b5f3bb79f3fd591ee32f123b9b9918b9469868b81afee662882af114f88a4fa1774215cfc1e67e1fed08d4a4fcfefecb420bf5b9ba962dab07446
+  data.tar.gz: e425eae9d1a0b3f2fd66434ce014ec67b02234c4451072f9c0f658384d9b8059731b58c95e2e48f2081c29fe68252d069da794a89531a19cfc36efdf43527251

data/CHANGELOG.textile

@@ -1,3 +1,10 @@
+*2.2*
+* Added a method to reboot servers.
+
+*2.1.1*
+* Virtual server upgrades no longer raise exceptions
+* Formalized the RDoc documentation process.  Added overview and welcome documentation and changed the README so it directs folks to the new documentation.
+
 *2.1.0*
 * Began implementing a model framework that allows Ruby developers to work with elements in the SoftLayer API in a more object-oriented fashion. The first release of this framework includes the Ticket, VirtualServer, and BareMetalServer classes.
 

data/examples/account_info.rb

@@ -26,7 +26,7 @@ require 'pp'
 
 begin
   softlayer_client = SoftLayer::Client.new(
-#    :username => "joecustomer"              # enter your username here
+#    :username => "joecustomer",            # enter your username here
 #    :api_key => "feeddeadbeefbadf00d..."   # enter your api key here
   )
 

data/lib/softlayer/Client.rb

@@ -30,11 +30,8 @@ module SoftLayer
   # - +:api_key+ - a non-empty string providing the api key to use for requests to the client
   # - +:endpoint_url+ - a non-empty string providing the endpoint URL to use for requests to the client
   #
-  # If any of the options above are missing then the constructor will try to use the corresponding
-  # global variable declared in the SoftLayer Module:
-  # - +$SL_API_USERNAME+
-  # - +$SL_API_KEY+
-  # - +$SL_API_BASE_URL+
+  # If any of these are missing then the Client class will look to the SoftLayer::Config
+  # class to provide the missing information.  Please see that class for details.
   #
   class Client
     # A username passed as authentication for each request. Cannot be emtpy or nil.
@@ -119,20 +116,18 @@ module SoftLayer
     def service_named(service_name, service_options = {})
       raise ArgumentError,"Please provide a service name" if service_name.nil? || service_name.empty?
 
-      # strip whitespace from service_name and
-      # ensure that it start with "SoftLayer_".
-      #
-      # if it does not, then add it
-      service_name.strip!
-      if not service_name =~ /\ASoftLayer_/
-        service_name = "SoftLayer_#{service_name}"
+      # Strip whitespace from service_name and ensure that it starts with "SoftLayer_".
+      # If it does not, then add the prefix.
+      full_name = service_name.to_s.strip
+      if not full_name =~ /\ASoftLayer_/
+        full_name = "SoftLayer_#{service_name}"
       end
 
       # if we've already created this service, just return it
       # otherwise create a new service
-      service_key = service_name.to_sym
+      service_key = full_name.to_sym
       if !@services.has_key?(service_key)
-        @services[service_key] = SoftLayer::Service.new(service_name, {:client => self}.merge(service_options))
+        @services[service_key] = SoftLayer::Service.new(full_name, {:client => self}.merge(service_options))
       end
 
       @services[service_key]

data/lib/softlayer/Config.rb

@@ -23,6 +23,59 @@
 require 'configparser'
 
 module SoftLayer
+
+  # The SoftLayer Config class is responsible for providing the key information 
+  # the library needs to communicate with the network SoftLayer API. Those three crucial
+  # pieces of information are the Username, the API Key, and the endpoint_url. This information
+  # is collected in a hash with the keys `:username`, `:api_key`, and `:endpoint_url` repsectively.
+  # 
+  # The routine used to retrieve this information from a Config object is Config.client_settings
+  #
+  # There are several locations that the Config class looks for this information:
+  #
+  # * Stored in a configuration file
+  # * In the Environment Variables of the running process
+  # * Placed in Global Variables
+  # * In a hash provided directly to the Config class.
+  #
+  # These locations are searched in the order listed above.  Information found
+  # lower in this list will replace the information found at higher levels.  For example
+  # if the configuration file provides a username but a different username is also set
+  # in the global variables, the Config class allows the global variable to override the name
+  # from the config file.
+  #
+  # = Config File
+  #
+  # The library will search for the SoftLayer config file at the file locations listed in
+  # the `SoftLayer::Config::FILE_LOCATIONS` array. The config file follows the format
+  # recognized by Python's ConfigParser class (and consequently is compatible with the)
+  # SoftLayer-Python language bindings).  A simple config file looks something like this:
+  #
+  #      [softlayer]
+  #      username = joeusername
+  #      api_key = DEADBEEFBADF00D
+  #
+  # = Environment Variables
+  #
+  # The config class will search the environment variables SL_USERNAME and SL_API_KEY for 
+  # the username and API key respectively. The endpoint_url may not be set thorugh
+  # environment variables.
+  #
+  # = Global Variables
+  #
+  # The names of the global variables that can be used to provide authentication key are:
+  #
+  # - +$SL_API_USERNAME+
+  # - +$SL_API_KEY+
+  # - +$SL_API_BASE_URL+
+  #
+  # = Direct parameters
+  #
+  # Finally, the Config.client_settings routine accepts a hash of arguments. If any
+  # of the key information is provided in that hash, that information will override
+  # any discovered through the techniques above.
+  #
+
 	class Config
 		def Config.globals_settings
 			result = {}
@@ -65,7 +118,8 @@ module SoftLayer
 		end
 
 		def Config.client_settings(provided_settings = {})
-			settings = file_settings
+      settings = { :endpoint_url => API_PUBLIC_ENDPOINT }
+			settings.merge! file_settings
 			settings.merge! environment_settings
 			settings.merge! globals_settings
 			settings.merge! provided_settings

data/lib/softlayer/ModelBase.rb

@@ -82,17 +82,6 @@ module SoftLayer
       @softlayer_hash = self.softlayer_properties(object_mask)
     end
 
-    ##
-    # Subclasses should implement this method as part of enabling the
-    # refresh_details fuctionality The implementation should make a request
-    # to the SoftLayer API and retrieve an up-to-date SoftLayer hash
-    # representation of this object. That hash should be the return value
-    # of this routine.
-    #
-    def softlayer_properties(object_mask = nil)
-      raise "Abstract method softlayer_properties in ModelBase was called"
-    end
-
     ##
     # Returns the value of of the given property as stored in the
     # softlayer_hash. This gives you access to the low-level, raw
@@ -132,6 +121,17 @@ module SoftLayer
 
     protected
 
+    ##
+    # Subclasses should implement this method as part of enabling the
+    # refresh_details fuctionality The implementation should make a request
+    # to the SoftLayer API and retrieve an up-to-date SoftLayer hash
+    # representation of this object. That hash should be the return value
+    # of this routine.
+    #
+    def softlayer_properties(object_mask = nil)
+      raise "Abstract method softlayer_properties in ModelBase was called"
+    end
+    
     ##
     # The softlayer_hash stores the low-level information about an
     # object as it was retrieved from the SoftLayer API.

data/lib/softlayer/ObjectFilter.rb

@@ -63,7 +63,7 @@ module SoftLayer
   # This class defines the routines that are valid within the block provided to a call to
   # ObjectFilter.build. This allows you to create object filters like:
   #
-  # object_filter = SoftLayer::ObjectFilter.build("hardware.memory") { is_greater_than(2) }
+  #     object_filter = SoftLayer::ObjectFilter.build("hardware.memory") { is_greater_than(2) }
   #
   class ObjectFilterBlockHandler
     # Matches when the value is found within the field

data/lib/softlayer/ProductPackage.rb

@@ -20,6 +20,8 @@
 # THE SOFTWARE.
 #
 
+require 'json'
+
 module SoftLayer
   ##
   # Each SoftLayer ProductPackage provides information about ordering a product
@@ -140,7 +142,7 @@ module SoftLayer
       softlayer_client = client || Client.default_client
       raise "#{__method__} requires a client but none was given and Client::default_client is not set" if !softlayer_client
       
-      filter = SoftLayer::ObjectFilter.build('type.keyName') { is(key_name) }
+      filter = SoftLayer::ObjectFilter.build('type.keyName', key_name)
       filtered_service = softlayer_client['Product_Package'].object_filter(filter).object_mask(self.default_object_mask('mask'))
       packages_data = filtered_service.getAllObjects
       packages_data.collect { |package_data| ProductPackage.new(softlayer_client, package_data) }

data/lib/softlayer/VirtualServer.rb

@@ -75,7 +75,7 @@ module SoftLayer
     #
     sl_dynamic_attr :upgrade_options do |resource|
       resource.should_update? do
-        @upgrade_items == nil
+        @upgrade_options == nil
       end
 
       resource.to_update do
@@ -365,7 +365,7 @@ module SoftLayer
     # and whose capacity matches the value given. Returns the item_price or nil
     #
     def _item_price_in_category(which_category, capacity)
-      item_prices_in_category = self.upgrade_items.select { |item_price| item_price["categories"].find { |category| category["categoryCode"] == which_category } }
+      item_prices_in_category = self.upgrade_options.select { |item_price| item_price["categories"].find { |category| category["categoryCode"] == which_category } }
       item_prices_in_category.find { |ram_item| ram_item["item"]["capacity"].to_i == capacity}
     end
 

data/lib/softlayer/base.rb

@@ -31,12 +31,12 @@ require 'rubygems'
 # - +$SL_API_BASE_URL+- The default URL used to access the SoftLayer API. This defaults to the value of +SoftLayer::API_PUBLIC_ENDPOINT+
 #
 module SoftLayer
-  VERSION = "2.1.0"  # version history in the CHANGELOG.textile file at the root of the source
+  VERSION = "2.1.1"  # version history in the CHANGELOG.textile file at the root of the source
 
-  # The base URL of the SoftLayer API's REST-like endpoints available to the public internet.
+  # The base URL of the SoftLayer API available to the public internet.
   API_PUBLIC_ENDPOINT = 'https://api.softlayer.com/xmlrpc/v3/'
 
-  # The base URL of the SoftLayer API's REST-like endpoints available through SoftLayer's private network
+  # The base URL of the SoftLayer API available through SoftLayer's private network
   API_PRIVATE_ENDPOINT = 'https://api.service.softlayer.com/xmlrpc/v3/'
 
   #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: softlayer_api
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.1.1
 platform: ruby
 authors:
 - SoftLayer Development Team
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-16 00:00:00.000000000 Z
+date: 2014-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: configparser
@@ -94,8 +94,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.textile
-- LICENSE.textile
-- README.textile
 - examples/account_info.rb
 - examples/account_servers.rb
 - examples/create_ticket.rb

data/LICENSE.textile

@@ -1,19 +0,0 @@
-Copyright (c) 2010-2014 "SoftLayer Technologies, Inc.":http://www.softlayer.com/ All rights reserved.
-
-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.textile

@@ -1,311 +0,0 @@
-h1=. SoftLayer API Client for Ruby
-
-The SoftLayer API Client for Ruby is a library for connecting to and calling the routines of "The SoftLayer API":http://sldn.softlayer.com/article/The_SoftLayer_API from the "Ruby":http://www.ruby-lang.org programming language.
-
-<div id="note" style="margin: 1em; padding: 0.5em; background-color: #fcfcfc; border: 1px solid black">
-	*Important Note*
-
-	If you are arriving at this build from verison 1.0 of the @softlayer_api@ gem, you will probably have to change some of your existing scripts. Please see "What's New":#whats-new for details.
-</div>
-
-h2. Overview
-
-The client invokes methods in the API using XML-RPC as a transport mechanism. XML-RPC is handled using @XMLRPC@ classes from the Ruby core library.
-
-To make calls to the Ruby API through the client you will create an instance of the @SoftLayer::Client@ class, optionally identifying an API endpoint, and providing authentication information in the form of a username and API key. From the client you can obtain various @SoftLayer::Service@ instances and use them to invoke the methods of the API. Results of those calls are communicated from the server to the client as XML, then decoded and returned to you as standard Ruby objects like Hashes, Arrays, and Strings.
-
-Source code for daily builds of this Gem can be found on the "SoftLayer github public repositories":http://github.com/softlayer/. The latest release version of the Gem is available from the Ruby gem system. (see "Installation":#installation below)
-
-Should you encounter problems with the client, please contact us in the "SoftLayer Developer Network forums":http://forums.softlayer.com/forum/softlayer-developer-network or open a support ticket in the SoftLayer customer portal.
-
-h2. Requirements
-
-The Ruby client has been tested using a wide variety of Ruby implementations including Ruby version 1.9.2, 2.0, and 2.1. It has also been tested on JRuby running in 1.9 mode.
-
-A network connection is required, and a valid SoftLayer API username and api key are required to call the SoftLayer API. A connection to the SoftLayer private network is required to connect to SoftLayer's private network API endpoints.
-
-h2(#whats-new). What's New
-
-The softlayer_api gem no longer supports Ruby 1.8.x
-
-**Version 2.1** of @softlayer_api@ builds an object model of SoftLayer clases on top of the low-level SoftLayer API calls. The object model provides a high-level interface to the elements within the SoftLayer environment and encapsulates some of the details of the "raw" SoftLayer API.
-
-
-With this first release, the Object Model provides classes for the SoftLayer Account, Bare Metal and Virutal servers, and Tickets. The model also provides classes to help you place orders for both Bare Metal and Virtual Servers. The class structure is not meant to be comprehensive.  Our goal is to provide a simple API for performing common operations.
-
-Interface documentation for the new object hierarchy is available in the gem's source. More comprehensive documentation including a design guide for new clases and a contribution guide for developers will be added in the future.
-
-**Version 2.0** of the @softlayer_api@ gem changes the protocol used to communicate with the SoftLayer API from REST to XML-RPC. This change alone should not require any changes to scripts written to the version 1.0 gem. However there are two new behaviors which will require existing version 1.0 scripts to change:
-
-* Object Masks are now sent to the server using the "Extended Object Mask Format":http://sldn.softlayer.com/article/Object-Masks.
-* Result limits are now specified using a single call rather than requiring two
-
-The gem now allows you to specify your SoftLayer username and API key through a config file. See "Providing authentication in a config file":#config_authorization for more information.
-
-h3. XML-RPC
-
-In the broad view of the SoftLayer API, when sending requests to the server, an API client may use "SOAP":http://sldn.softlayer.com/article/SOAP, "XML-RPC":http://sldn.softlayer.com/article/XML-RPC, or "REST":http://sldn.softlayer.com/article/REST. Previous versions of the SoftLayer API Gem used REST to communicate with the server. This version uses XML-RPC. Adopting the XML-RPC transport mechanism allows the Gem to take adavantage of features of the API that are not available through the REST interface.
-
-h3. Extended Object Masks
-
-In previous versions of the SoftLayer Gem the @object_mask@ call modifier accepted Ruby structres like Arrays and Hashes and would do its best to construct Object Masks from them. @object_mask@ now expects masks to be passed as strings in the "Object Mask":http://sldn.softlayer.com/article/Object-Masks format and passes them through to the API for processing. If you are using @object_mask@, you will probably have to change your existing scripts.
-
-The Gem extends the Ruby @Hash@ class with a method, @to_sl_object_mask@, which can help with the conversion between masks made of structured objects and the string format. This method, however, must be called explicitly. Here is an example of calling @to_sl_object_mask@:
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">mask_hash = { "mask" => ["id", {"assignedUser" => ["id", "username"]}, "createDate"],
-	"mask(SoftLayer_Hardware_Server)" => ["id", "bareMetalInstanceFlag"] }
-mask_string = mask_hash.to_sl_object_mask
-# mask_string is "[mask[id,assignedUser[id,username],createDate],mask(SoftLayer_Hardware_Server)[id,bareMetalInstanceFlag]]"
-</code></pre>
-
-h3. Result Limits
-
-In previous versions of the SoftLayer API Gem, result limits were specified using two API filters:
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">account_service.result_offset(3).result_limit(5).getOpenTickets  # this is the "old way" of specifying a result limit
-</code></pre>
-
-These two API filters have been combined into a single result limits filter:
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">account_service.result_limit(3, 5).getOpenTickets # this is the "new way" of supplying a result limit
-</code></pre>
-
-h2(#installation). Installation
-
-The Ruby client is available as the @softlayer_api@ Ruby gem. On most systems, the command:
-
-@gem install softlayer_api@
-
-installs the gem and makes it available to Ruby scripts. Where the gem is installed on your computer will depend on your particular distribution of Ruby. Refer to the gem documentation for your distribution for more information.
-
-h2. Usage
-
-To begin using the Ruby client, you will have to create an instance of the @SoftLayer::Client@. From the Client you must obtain @SoftLayer::Service@ objects corresponding to each of the "API Services":http://sldn.softlayer.com/reference/services that your code wants to call. To create the client instance, you will have to provide information that the library will use to authenticate your account with the API servers.
-
-h3. Authentication
-
-That instance will have to know your "API authentication information":http://sldn.softlayer.com/article/Authenticating_to_the_SoftLayer_API consisting of your account username and API key. In addition, you will have to select an endpoint, the web address the client will use to contact the SoftLayer API. You may provide this information in a configuration file, through global variables, or by passing them to the constructor.
-
-h4(#config_authorization). Providing authentication in a config file
-
-The Ruby client will look for a configuration file that can provide the username and api_key for requests. A sample configuraiton file looks like this:
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">[softlayer]
-username = joeusername
-api_key = DEADBEEFBADF00D
-</code></pre>
-
-It is important that the config file declare the section "softlayer". The keys accepted in that section are @username@, @api_key@, and @endpoint_url@. You will have to provide an explicit endpoint url, for example, if you want to use the SoftLayer private network API endpoint.
-
-The client will look for configuration files in your home directory under the name ".softlayer" or in the directory @/etc/softlayer.conf@
-
-h4. Providing authentication information through Globals
-
-The SoftLayer Ruby Client makes use of three global variables, in the @SoftLayer@ name space, related to creating instances of the @SoftLayer::Service@ class:
-
-table{position:relative;left:2em;width:80%}.
-|{vertical-align:baseline;width:30%}.@$SL_API_USERNAME@|A string used as the default username used when creating @Service@ objects|
-|{vertical-align:baseline}.@$SL_API_KEY@|A string used as the default API key used when creating @Service@ objects.|
-|{vertical-align:baseline}.@$SL_API_BASE_URL@|The endpoint base URL used by the service. This variable defaults to @API_PUBLIC_ENDPOINT@ |
-
-If you are going to create a lot of different @Service@ objects and they are all going to use the same authentication information it may be convenient to set the values in these globals.
-
-In addition to the globals, the @SoftLayer@ namespace defines two constants representing the endpoints for the SoftLayer API on the private and public networks:
-
-table{position:relative;left:2em;width:80%}.
-|{vertical-align:baseline;width:35%}.@API_PUBLIC_ENDPOINT@|A constant containing the base address for the public network XML-RPC endpoint of the SoftLayer API - @https://api.softlayer.com/xmlrpc/v3/@|
-|{vertical-align:baseline}.@API_PRIVATE_ENDPOINT@|A constant containing the base address for the private network XML-RPC endpoint of the SoftLayer API - @https://api.service.softlayer.com/xmlrpc/v3/@|
-
-For more information about the two networks see "Choosing_the_Public_or_Private_Network":http://sldn.softlayer.com/article/The_SoftLayer_API#Choosing_the_Public_or_Private_Network. You can change the default endpoint URL by setting the global variable @$SL_API_BASE_URL@ to either of these two values.
-
-Here is an example of using these globals to create a service:
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">$SL_API_USERNAME = "joeusername";
-$SL_API_KEY = "omitted_for_brevity"
-
-client = SoftLayer::Client.new()
-account_service = client.service_named("Account")
-</code></pre>
-
-Note that the endpoint URL is not specified. The default endpoint URL is set to the @API_PUBLIC_ENDPOINT@
-
-h4. Providing authentication information through the Constructor
-
-You can provide the authentication information needed by a @Client@ object as hash arguments in the constructor. The keys used in the hash arguments are symbols whose values should be strings:
-
-table{position:relative;left:2em;width:80%}.
-|{vertical-align:baseline;width:30%}.@:username@|The username used to authenticate with the server.|
-|{vertical-align:baseline}.@:api_key@|The API key used to authenticate with the server.|
-|{vertical-align:baseline}.@:endpoint_url@|The endpoint address that will receive the method calls.|
-
-Here is an example, analogous to the one for global variables, which provides the username and API key as hash arguments. This example also changes the endpoint with the @:endpoint_url@ symbol so that the service will use the API on the SoftLayer Private Network:
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">client = SoftLayer::Client.new(:username => "joeusername",
-    :api_key => "omitted_for_brevity",
-    :endpoint_url => API_PRIVATE_ENDPOINT)
-account_service = client.service_named("Account")
-</code></pre>
-
-h3. Calling Service Methods
-
-With an instance of @SoftLayer::Service@ in hand, you can call the methods provided by that service. Calling a API method on a service is as easy as calling a Ruby method on the service object. For example, given the @account_service@ objects created above, a call to get a list of the open tickets on an account using the @SoftLayer_Account@ service's @getOpenTickets@ method would look like this:
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">open_tickets = account_service.getOpenTickets
-</code></pre>
-
-If the method requires arguments, you can supply them as arguments to the method you're calling on the service object. The arguments should be arguments that XML-RPC can encode into XML. Generally this means your argument should be hashes, arrays, strings, numbers, booleans, or nil.
-
-Here is an example of calling the @createStandardTicket@ method on a ticket service. This example also uses the "bracket" syntax on a client @client['<service-name>']@ to obtain the service object:
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">#authentication information will be found in the global variables
-client = SoftLayer::Client.new()
-ticket_service = client['Ticket']
-new_ticket = ticket_service.createStandardTicket(
-{
-    "assignedUserId" => my_account_id,
-    "subjectId" => 1022,
-    "notifyUserOnUpdateFlag" => true
-},
-"This is a test ticket created from a Ruby client")
-</code></pre>
-
-h4. Identifying Particular Objects
-
-Some method calls in the SoftLayer API are made on particular objects, rather than on the services themselves. These objects, however, are always obtained by a service. To call a method on a particular object you can chain a call to @object_with_id@ onto the service that provides the object in question. @object_with_id@ takes one argument, the object id of the object you are interested in. For example, if you were interested in getting the Ticket with a ticket id of 123456 you could so so by calling:
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">ticket_of_interest = ticket_service.object_with_id(123456).getObject
-</code></pre>
-
-The @object_with_id@ call returns an object that you can use as a reference to a particular object through the service. This allows you to reuse that object multiple times without having to repeatedly tack @object_with_id@ on to all your requests. For example, if you want to find a ticket with the id 98765 and add an update to it if it's assigned to user 123456, you might write code like this:
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">begin
-    ticket_ref = ticket_service.object_with_id(98765)
-    ticket = ticket_ref.object_mask("mask.assignedUserId").getObject
-    if ticket['assignedUserId'] == 123456
-        updates = ticket_ref.addUpdate({"entry" => "Get to work on these tickets!"})
-    end
-rescue Exception => exception
-    puts "An error occurred while updating the ticket: #{exception}"
-end
-</code></pre>
-
-The code creates a variable named @ticket_ref@ which refers to ticket 98765 through the tickets_service. This @ticket_ref@ is used with an @object_mask@ to retrieve the ticket and, if the ticket meets the conditional requirement, that same @ticket_ref@ is reused to add an update to the ticket.
-
-h4. Adding an Object Mask
-
-If you wish to limit the volume of information that the server returns about a particular object, you can use an Object Mask to indicate exactly which attributes you are interested in. To provide an Object Mask you simply insert a call to @object_mask@ in the call chain for the method you are invoking.
-
-The arguments to @object_mask@ must strings. Each string should be a well defined Object Mask as defined in the "SLDN documentation":http://sldn.softlayer.com/article/Object-Masks.
-
-To look at some examples, consider the following object from the server. It has four properties: @id@, @title@, @createDate@ and @modifyDate@. It also has an entity, @assignedUser@. The @assignedUser@ entity has three properties: @id@, @username@, and @health@.
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">{
-    "id"=>1736473,
-    "title"=>"VM Polling Failure - unable to login",
-    "createDate"=>"2010-04-22T00:12:36-05:00",
-    "modifyDate"=>"2010-06-09T06:44:18-05:00"
-    "assignedUser"=> {
-        "id"=>14
-        "username"=>"AlfredQHacker",
-        "health"=>"Fantastic"
-    },
-}</code></pre>
-
-If we were making a request to the server to retrieve this object, or an array of such objects, we might want to limit the response so that it contains just the @id@ fields:
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">an_api_service.object_mask("mask.id").getObject
-=> {"id"=>1736473}
-</code></pre>
-
-If we want more than one property back from the server the call to @object_mask@ can identify multiple properties as separate argumnents:
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">an_api_service.object_mask("mask[id,createDate]").getObject
-=> {"id"=>1736473, "createDate"=>"2010-04-22T00:12:36-05:00"}
-</code></pre>
-
-If we ask for the @assignedUser@ we get back that entire entity:
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">an_api_service.object_mask("mask.assignedUser").getObject
-=> {"assignedUser"=> {"id"=>14, "username"=>"AlfredQHacker", "health"=>"Fantastic"}}
-</code></pre>
-
-However, we may not be interested in the entire assigned user entity, we may
-want to get just the id of the assigned user:
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">an_api_service.object_mask("mask[assignedUser.id]").getObject
-=> {"assignedUser"=>{"id"=>14}}
-</code></pre>
-
-We can identify a particular set of attributes we are interested in by combining Object Mask forms:
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">an_api_service.object_mask("mask[assignedUser[id,health]]").getObject # retrieving multiple properties
-=> {"assignedUser"=>{"id"=>14, "health"=>"Fantastic"}}
-</code></pre>
-
-Object masks are sent to the server and applied on the server side. Errors in the object mask format will lead to exceptions being thrown by the SoftLayer API. By carefully choosing an Object Mask, you can limit amount of information transferred from the server which may improve bandwidth and processing time.
-
-You @object_with_id@ should only be called once in any calling sequence. You may call @object_mask@ multiple times, but the server may generate a warning if the Object Masks ask for duplicate properties of some object.
-
-h2. Examples
-
-Here are some examples that demonstrate using the SoftLayer API Ruby Client. The authentication information, of course, is left as an exercise for the reader. The first example uses the @getObject@ method of the "SoftLayer_Account":http://sldn.softlayer.com/reference/services service:
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">require 'rubygems'
-require 'softlayer_api'
-require 'pp'
-
-begin
-  # use an account service to get a list of the open tickets and print their IDs and titles
-  client = SoftLayer::Client.new(
-    :username => "joecustomer",             # enter your username here
-    :api_key => "feeddeadbeefbadf00d...")   # enter your api key here
-
-  account_service = client['Account']
-  account = account_service.getObject
-  pp account
-rescue Exception => exception
-  puts "Unable to retrieve account information: #{exception}"
-end
-</code></pre>
-
-This second example retrieves some of the information in a support ticket then adds and update to that ticket. It uses an object_with_id to create an object
-that references a ticket with a particular ID and reuses that reference later to refer to the same ticket. It combines that reference with an @object_mask@ to limit the amount of information transferred from the server.
-
-<pre style="border:1pt solid black;background:#eee;padding:0.5em;margin:0.5em"><code style="font-family:Menlo,Monaco,monospace;font-size:9pt">require 'rubygems'
-require 'softlayer_api'
-require 'pp'
-
-client = SoftLayer::Client.new()
-  :username => "joecustomer",              # enter your username here
-  :api_key => "feeddeadbeefbadf00d...")    # enter your api key here
-
-ticket_service = client.service_named('Ticket')
-
-begin
-  # this creates an alias to the ticket service bound to the ticket with the id 123456
-  ticket_ref = ticket_service.object_with_id(123456) # you'll have to substitute your own ticket ID
-
-  ticket = ticket_ref.object_mask("mask[updates[entry,createDate],assignedUserId,attachedHardware.datacenter]").getObject
-  pp ticket
-rescue Exception => exception
-  puts "Unable to retrieve the ticket"
-end
-
-# update the ticket
-begin
-  updates = ticket_ref.addUpdate({"entry" => "An update from the Ruby client!"})
-  puts "Update ticket 123456. The new update's id is #{updates[0]['id']}"
-rescue Exception => exception
-  puts "Unable to update the ticket: #{exception}"
-end
-</code></pre>
-
-h2. Author
-
-This software is written by the SoftLayer Development Team <"sldn@softlayer.com":mailto:sldn@softlayer.com>.
-
-Please join us in the "SoftLayer Developer Network forums":http://forums.softlayer.com/forum/softlayer-developer-network
-
-h2. Copyright
-
-This software is Copyright (c) 2010-2014 "SoftLayer Technologies, Inc":http://www.softlayer.com/. See the bundled LICENSE.textile file for more information.