softlayer_api 1.0.8 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f7f6dacd2a3f7e2589109a815000ed208497963e
-  data.tar.gz: b8b38d3cdaa828b98508ba13e494d0b771257c70
+  metadata.gz: 138098883bbed45430cd5f87cf3a55f3c44cec86
+  data.tar.gz: e0759954adc4ced91c4af376a3186cee67e6d8b3
 SHA512:
-  metadata.gz: b80012657f2387a7ef60bfb284a64e2fa65ff6f8095a8b074d6992504f461b4547215607c583943ce13d86e9790fb7eddf8e5a3af90ca89eabb24293a3c7d5bf
-  data.tar.gz: aa3cc1087a9449539d69c29277a73b4a436afe61ce5ec1b25a9235e0bb4aa7dbc5af747e1fe60dc3eff5de63f5a4d224490977832742b87f59f6b8c28569ec25
+  metadata.gz: bb2b89e1893eaafe7d07f07b9e0e96de18e158aadd1fe97ce0b45ca817c64bd434cb8995e0add07b54334086eb848fa692fc172dd0a2ec78ff53e9d0c6e84319
+  data.tar.gz: 1cf7a2aa2fc70c5b84b2405cc201e3da0a46d1e57ba8ea172cd239b791366268bc1016514fd9546d2cd5734975e47bb280b92cb562a360eceefb0977b02d5b9c

data/README.textile

@@ -2,23 +2,63 @@ 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*
+
+	Version 2.0 of the gem may require you change your existing scripts. Please see "What's New":#whats_new for details.
+</div>
+
 h2. Overview
 
-The client invokes methods in the API using a REST inspired URL scheme. HTTP calls are handled using the Net::HTTP classes that are part of the Ruby core library.
+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::Service@ class, optionally identifying an API endpoint, and providing authentication information in the form of a username and API key. You then make calls to the SoftLayer API by calling methods on the Service object. Results of those calls are communicated from the server to the client as JSON objects and then decoded and returned to you as standard Ruby objects.
+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 the most up to date version of this library can be found on the "SoftLayer github public repositories":http://github.com/softlayer/. The latest library should also be available as a Ruby gem. (see "Installation":#installation below)
+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 on the "SoftLayer forums":http://forums.softlayer.com/ or open a support ticket in the SoftLayer customer portal.
+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 using both Ruby 1.8 and Ruby 1.9.
+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
+
+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 should not require any changes to existing scripts. However there are two new behaviors which may require you to change existing scripts:
+* 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
+
+Version 2.0 does not support Ruby 1.8.x
+
+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>
 
-This gem relies on the JSON library which, at the time of this writing, is called simply @json@ for most Ruby implementations and @json-jruby@ for JRuby.  Correspondingly we have created a @softlayer_api@ gem and a @softlayer_api_jruby@ gem to account for the difference.
+These two API filters have been combined into a single result limits filter:
 
-A network connection is required, and a valid SoftLayer API username and 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.
+<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
 
@@ -30,13 +70,24 @@ installs the gem and makes it available to Ruby scripts. Where the gem is instal
 
 h2. Usage
 
-To begin using the Ruby client, you will have to create an instance of the @SoftLayer::Service@ class for each the "API Services":http://sldn.softlayer.com/reference/services that your code will call. To create the instance, you will have to provide information that the library will use to authenticate your account with the API servers.
-
-Once you have created a service object, you will use that service object to call methods in the SoftLayer API.
+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 either through global variables, or by passing them to the constructor.
+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. 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
 
@@ -52,8 +103,8 @@ If you are going to create a lot of different @Service@ objects and they are all
 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 REST inspired endpoint of the SoftLayer API - @https://api.softlayer.com/rest/v3/@|
-|{vertical-align:baseline}.@API_PRIVATE_ENDPOINT@|A constant containing the base address for the private network REST inspired endpoint of the SoftLayer API - @https://api.service.softlayer.com/rest/v3/@|
+|{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.
 
@@ -62,14 +113,15 @@ 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"
 
-account_service = SoftLayer::Service.new("SoftLayer_Account")
+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 @Service@ object as hash arguments in the constructor. The keys used in the hash arguments are symbols whose values should be strings:
+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.|
@@ -78,10 +130,10 @@ table{position:relative;left:2em;width:80%}.
 
 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">account_service = SoftLayer::Service.new("SoftLayer_Account",
-    :username => "joeusername",
+<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
@@ -91,10 +143,13 @@ With an instance of @SoftLayer::Service@ in hand, you can call the methods provi
 <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 can be encoded using the JSON encoder provided by the @json@ gem.  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:
+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
-ticket_service = SoftLayer::Service.new("SoftLayer_Ticket")
+client = SoftLayer::Client.new()
+ticket_service = client['Ticket']
 new_ticket = ticket_service.createStandardTicket(
 {
     "assignedUserId" => my_account_id,
@@ -106,16 +161,16 @@ new_ticket = ticket_service.createStandardTicket(
 
 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:
+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:
+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("assignedUserId").getObject
+    ticket = ticket_ref.object_mask("mask.assignedUserId").getObject
     if ticket['assignedUserId'] == 123456
         updates = ticket_ref.addUpdate({"entry" => "Get to work on these tickets!"})
     end
@@ -126,15 +181,13 @@ end
 
 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
+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.
+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 can be strings, arrays, or hashes. The Strings provide the names of properties you are interested in and the hash and array elements allow you to structure your mask much as the properties themselves are structured.
+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 and an entity, and id, a title, a createDate (giving the date it was create), a modifyDate (the date it was last modified), and an assignedUser entity.
-
-The assignedUser entity has three properties, id, username, and health.
+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,
@@ -146,99 +199,94 @@ The assignedUser entity has three properties, id, username, and health.
         "username"=>"AlfredQHacker",
         "health"=>"Fantastic"
     },
-}
-</code></pre>
+}</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:
+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("id").getObject
+<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("id", "createDate").getObject  # object_mask with multiple arguments
-=> {"id"=>1736473, "createDate"=>"2010-04-22T00:12:36-05:00"}
-</code></pre>
-
-or it can include them in an array:
-
-<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(["id", "createDate"]).getObject # multiple mask items presented in an array
+<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:
+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("assignedUser").getObject
+<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. To do that we pass a hash argument to @object_mask@.  The has follows the hierarchical nature of the properties
+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({"assignedUser" => "id"}).getObject # using a hash to access the property hierarchy
+<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 the array and hash forms:
+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({"assignedUser" => ["id", "health"]}).getObject # retrieving multiple properties
+<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. By carefully choosing an object mask, you can limit amount of information transferred from the server which may improve bandwidth and processing time.
+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 may add calls to both @object_mask@ and @object_with_id@, but only one call to each should appear in any calling sequence.
+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:
+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
-    account_service = SoftLayer::Service.new("SoftLayer_Account",
+  # 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 = account_service.getObject
-    pp account
+  account_service = client['Account']
+  account = account_service.getObject
+  pp account
 rescue Exception => exception
-    puts "Unable to retrieve account information: #{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.
+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'
 
-ticket_service = SoftLayer::Service.new("SoftLayer_Ticket",
-    :username => "joecustomer",              # enter your username here
-    :api_key => "feeddeadbeefbadf00d...")    # enter your api key here
+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
-    ticket_ref = ticket_service.object_with_id(123456)
+  # 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({"updates" => ["entry", "createDate"]},
-                                    "assignedUserId",
-                                    {"attachedHardware" => "datacenter"}).getObject
-    pp ticket
+  ticket = ticket_ref.object_mask("mask[updates[entry,createDate],assignedUserId,attachedHardware.datacenter]").getObject
+  pp ticket
 rescue Exception => exception
-	puts "Unable to retrieve the ticket"
+  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']}"
+  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}"
+  puts "Unable to update the ticket: #{exception}"
 end
 </code></pre>
 
@@ -246,6 +294,8 @@ 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.

data/examples/{accountInformation.rb → account_info.rb}

@@ -25,11 +25,13 @@ require 'softlayer_api'
 require 'pp'
 
 begin
-	# use an account service to get a list of the open tickets and print their IDs and titles
-	account_service = SoftLayer::Service.new("SoftLayer_Account",
-  	:username => "joecustomer"              # enter your username here
-  	:api_key => "feeddeadbeefbadf00d...")   # enter your api key here
+  softlayer_client = SoftLayer::Client.new(
+    :username => "joecustomer"              # enter your username here
+    :api_key => "feeddeadbeefbadf00d..."   # enter your api key here
+  )
 
+	# use an account service to get a list of the open tickets and print their IDs and titles
+	account_service = softlayer_client['Account'];
 	account = account_service.getObject
 	pp account
 rescue Exception => exception

data/examples/{createTicket.rb → create_ticket.rb}

@@ -29,13 +29,16 @@ require 'pp'
 $SL_API_USERNAME = "joecustomer"         # enter your username here
 $SL_API_KEY = "feeddeadbeefbadf00d..."   # enter your api key here
 
+softlayer_client = SoftLayer::Client.new()
 begin
   # use an account service to get the account ID of my account
-  account_service = SoftLayer::Service.new("SoftLayer_Account")
+  account_service = softlayer_client.service_named("Account")
   my_account_id = account_service.getCurrentUser['id']
 
   # Use a ticket service to create a standard support ticket, assigned to me.
-  ticket_service = SoftLayer::Service.new("SoftLayer_Ticket")
+  # Note: calling for the Ticket service using the brackets is entirely equivalent
+  # go calling service_named('Ticket')
+  ticket_service = softlayer_client['Ticket']
   new_ticket = ticket_service.createStandardTicket(
                   {
                     "assignedUserId" => my_account_id,
@@ -47,7 +50,7 @@ begin
   puts "Created a new ticket : #{new_ticket['id']} - #{new_ticket['title']}"
 
   # add an update to the newly created ticket.
-  pp ticket_service.object_with_id(new_ticket['id']).edit(nil, "This is a ticket update sent from the Ruby library")
+  pp ticket_service.object_with_id(new_ticket['id']).edit({}, "This is a ticket update sent from the Ruby library")
 rescue Exception => exception
   $stderr.puts "An exception occurred while trying to complete the SoftLayer API calls #{exception}"
 end

data/examples/{openTickets.rb → open_tickets.rb}

@@ -27,9 +27,11 @@ require 'pp'
 $SL_API_USERNAME = "joecustomer"         # enter your username here
 $SL_API_KEY = "feeddeadbeefbadf00d..."   # enter your api key here
 
+softlayer_client = SoftLayer::Client.new()
+
 # use an account service to get a list of the open tickets and print their
 # IDs and titles
-account_service = SoftLayer::Service.new("SoftLayer_Account")
+account_service = softlayer_client.service_named("Account")
 
 open_tickets = account_service.getOpenTickets
 open_tickets.each { |ticket| puts "#{ticket['id']} - #{ticket['title']}" }
@@ -38,11 +40,11 @@ open_tickets.each { |ticket| puts "#{ticket['id']} - #{ticket['title']}" }
 # information known about it. We've already collected this information above,
 # but this will demonstrate using an object mask to filter the results from
 # the server.
-ticket_service = SoftLayer::Service.new("SoftLayer_Ticket")
+ticket_service = softlayer_client["Ticket"]
 open_tickets.each do |ticket|
   begin
-    pp ticket_service.object_with_id(ticket["id"]).object_mask( "id", "title", "createDate", "modifyDate", { "assignedUser" => ["id", "username", "email"] }).getObject
+    pp ticket_service.object_with_id(ticket["id"]).object_mask("mask[id,title,createDate,modifyDate,assignedUser[id,username,email]]").getObject
   rescue Exception => exception
-    puts "exception #{e}"
+    puts "exception #{exception}"
   end
 end

data/examples/ticket_info.rb

@@ -24,19 +24,19 @@ require 'rubygems'
 require 'softlayer_api'
 require 'pp'
 
-ticket_service = SoftLayer::Service.new("SoftLayer_Ticket",
+softlayer_client = SoftLayer::Client.new(
   :username => "joecustomer",              # enter your username here
-  :api_key => "feeddeadbeefbadf00d...")    # enter your api key here
+  :api_key => "feeddeadbeefbadf00d..."     # enter your api key here
+  )
 
 begin
-  ticket_ref = ticket_service.object_with_id(1683973)
+  ticket_service = softlayer_client.service_named("Ticket");
+  ticket_ref = ticket_service.object_with_id(8172109)
 
-  ticket = ticket_ref.object_mask({"updates" => ["entry", "createDate"]},
-                                  "assignedUserId",
-                                  {"attachedHardware" => "datacenter"}).getObject
+  ticket = ticket_ref.object_mask("mask[updates[entry,createDate],assignedUserId,attachedHardware.datacenter]".getObject
   pp ticket
 rescue Exception => exception
-	puts "Unable to retrieve the ticket"
+  puts "Unable to retrieve the ticket"
 end
 
 # update the ticket
@@ -44,5 +44,5 @@ 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}"
+  puts "Unable to update the ticket: #{exception}"
 end