softlayer_api 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e26524e94d4196b7efe0c8be5ada177ffc334868
-  data.tar.gz: 976cad936e4815d8ff6e9bc9afe7dd82fd22a1d5
+  metadata.gz: ec9821bee592ef106f6fd3cc00af8c1b980766a8
+  data.tar.gz: 3bda1cb83614eb4a8876a96aaad86d3104825ddb
 SHA512:
-  metadata.gz: a5c779a8e05b1e485837f9e740be51cd299947f7d859975388d9fa0b0cc20dee7bff643dd94095cee441b29e749c92da805df274d733870ec0d4106f04f3c950
-  data.tar.gz: 5c38cb7d6aa8f8057fecdbd19b3e37ae5a673104e7ae92206c4513c475dd3dadc1ee83f7d7462ce4cb69c0b2ae627b0019e32af20b71a8aa49de11d35d335a58
+  metadata.gz: b885072f2075801dc2f0a5dddb3ca0f902c560522d4cd2b9c7fb87f51761242a197fdd8c550a6a3ef2f10dabe6fb6c6fe8433964271f653a4c7afaac4b7618e5
+  data.tar.gz: 5c182f1f9633948a8b94bc7824f383434e23f468a9eb3a849b719849f56cbafda0af793a0c9e95fbfeca166b1f676da94963b1d3f7b8eaa9c3541daeb6d3f74a

data/CHANGELOG.textile

@@ -0,0 +1,36 @@
+*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.
+
+*2.0.1*
+* Fix broken gem configparser dependency
+
+*2.0.0*
+* Switched the Ruby API client to use XML-RPC when calling the SoftLayer API rather than using the REST-like interface.
+* Result limits are now specified using @result_limit(offset,limit)@.
+The @result_offset@ API filter has been removed.
+* The @object_mask@ call modifier no longer accepts Ruby structures. It accepts strings that are Object Masks in the "Extended Object Mask":http://sldn.softlayer.com/article/Object-Masks format.
+* Changed the mechanism for obtaining services to include the Client class. This makes the Ruby API very similar to the API presented by the Python bindings. The old mechanism for obtaining services still works to preserve backward compatibility but you will receive deprecation warnings in debug mode.
+
+*1.0.8*
+* Set a default User-Agent string to be sent with all requests to SoftLayer API. Provide interface to set a custom User-Agent string.
+
+*1.0.7*
+* Calls to the @getObject@ method of any service should not take parameters. The gem now warns if you make this type of call and ignores the parameters. This prevents @SoftLayer_Virtual_Guest::getObject@ from accidentally creating (billable) VirtualServer instances.
+
+*1.0.6*
+* Make all API calls with either a @GET@ or a @POST@ as the HTTP verb.
+
+*1.0.5*
+* Fixed a bug where empty hashes and empty arrays would not generate meaningful object masks
+
+*1.0.4*
+* Fixed a bug where the @result_limit@ and @result_offset@ object filters were just not working.
+
+*1.0.3*
+* Added a request filter to add result limits to request. Submitted by JN. Thanks!
+
+*1.0.2*
+* We have some API routines that start with 'get' but expect arguments anyway. The code now uses HTTP POST to send requests for which the user has provided arguments regardless of the name of the routine.
+
+*1.0*, *1.0.1*
+* Initial release of the gem

data/README.textile

@@ -5,7 +5,7 @@ The SoftLayer API Client for Ruby is a library for connecting to and calling the
 <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.
+	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
@@ -24,13 +24,23 @@ The Ruby client has been tested using a wide variety of Ruby implementations inc
 
 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
+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:
 
-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
+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
 
@@ -76,7 +86,7 @@ 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. Providing authentication in a config file
+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:
 
@@ -187,7 +197,7 @@ If you wish to limit the volume of information that the server returns about a p
 
 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@.
+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,
@@ -232,7 +242,7 @@ We can identify a particular set of attributes we are interested in by combining
 => {"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.
+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.
 

data/examples/account_info.rb

@@ -26,13 +26,16 @@ require 'pp'
 
 begin
   softlayer_client = SoftLayer::Client.new(
-    :username => "joecustomer"              # enter your username here
-    :api_key => "feeddeadbeefbadf00d..."   # enter your api key here
+#    :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
+	# Demonstrates using the low-level capabilities of the softlayer_api
+  # gem to get directly at methods in the SoftLayer API and extract
+  # data from them.
 	account_service = softlayer_client['Account'];
 	account = account_service.getObject
+
 	pp account
 rescue Exception => exception
 	puts "Unable to retrieve account information: #{exception}"

data/examples/account_servers.rb

@@ -0,0 +1,48 @@
+#
+# Copyright (c) 2014 SoftLayer Technologies, Inc. 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.
+#
+
+require 'rubygems'
+require 'softlayer_api'
+require 'pp'
+  
+  # We can set the default client to be our client and that way 
+  # we can avoid supplying it later
+  SoftLayer::Client.default_client = SoftLayer::Client.new(
+    # :username => "joecustomer"              # enter your username here
+    # :api_key => "feeddeadbeefbadf00d..."   # enter your api key here
+  )
+
+  account = SoftLayer::Account.account_for_client()
+
+  # grab a list of all the servers on the account.
+  servers = account.servers
+
+  # measure their fully qualified domain names so we can print a pretty table
+  max_name_len = servers.inject(0) { |max_name, server| [max_name, server.fullyQualifiedDomainName.length].max }
+
+  printf "%#{-max_name_len}s\tPrimary Public IP\n", "Server FQDN"
+  printf "%#{-max_name_len}s\t-----------------\n", "-----------"
+
+  servers.each do |server|
+    ip_field = server.primary_public_ip ? server.primary_public_ip : "No Public Interface"
+    printf "%#{-max_name_len}s\t#{ip_field}\n", server.fullyQualifiedDomainName
+  end

data/examples/create_ticket.rb

@@ -24,33 +24,44 @@ require 'rubygems'
 require 'softlayer_api'
 require 'pp'
 
-# We're creating more than one service so we'll use the globals to establish
-# the username and API key.
-$SL_API_USERNAME = "joecustomer"         # enter your username here
-$SL_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
+)
 
-softlayer_client = SoftLayer::Client.new()
 begin
-  # use an account service to get the account ID of my account
-  account_service = softlayer_client.service_named("Account")
-  my_account_id = account_service.getCurrentUser['id']
+  # To create a ticket we have to assign the ticket to some user so
+  # assign our new ticket to the current user
+  account = SoftLayer::Account.account_for_client(softlayer_client)
+  account_user = account.service.getCurrentUser
+  my_user_id = account_user["id"]
+  
+  # We also need a subject for the ticket. Subjects are specified by id
+  # This code prints out a table of all the ticket subjects with their
+  # ids:
+  ticket_subjects = SoftLayer::Ticket.ticket_subjects(softlayer_client)
+  ticket_subjects.each do |subject|
+    puts "#{subject['id']}\t#{subject['name']}"
+  end
+  
+  # For this example we'll use 'Public Network Question' as the subject.  That's id 1022
+  public_network_question_id = 1022
 
-  # Use a ticket service to create a standard support ticket, assigned to me.
-  # 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,
-                    "subjectId" => 1022,
-                    "notifyUserOnUpdateFlag" => true
-                  },
-                  "This is a test ticket created from a Ruby client")
+  # A title is optional, but we'll provide one and we offer the body of the ticket
+  # remember to pass the client to create_standard_ticket
+  new_ticket = SoftLayer::Ticket.create_standard_ticket(
+    :client => softlayer_client,
+    :title => "This is a test ticket, please simply close it",
+    :body => "This test ticket was created to test the Ruby API client.  Please ignore it.",
+    :subject_id => public_network_question_id,
+    :assigned_user_id => my_user_id
+  )
 
-  puts "Created a new ticket : #{new_ticket['id']} - #{new_ticket['title']}"
+  puts "Created a new ticket : #{new_ticket.id} - #{new_ticket.title}"
+  
+  # we can also add an update to the ticket:
+  new_ticket.update("This is a ticket update sent from the Ruby library")
 
-  # add an update to the newly created ticket.
-  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/open_tickets.rb

@@ -24,27 +24,22 @@ require 'rubygems'
 require 'softlayer_api'
 require 'pp'
 
-$SL_API_USERNAME = "joecustomer"         # enter your username here
-$SL_API_KEY = "feeddeadbeefbadf00d..."   # enter your api key here
+# One way to provide a username and api key is to provide them
+# as globals.
+# $SL_API_USERNAME = "joecustomer"         # enter your username here
+# $SL_API_KEY = "feeddeadbeefbadf00d..."   # enter your api key here
 
-softlayer_client = SoftLayer::Client.new()
+# The client constructed here must get it's credentials from somewhere
+# In this script you might uncomment the globals above and assign your 
+# credentials there
+SoftLayer::Client.default_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_client.service_named("Account")
+# The openTickets routine will pick up the default client established above.
+open_tickets = SoftLayer::Ticket.open_tickets()
 
-open_tickets = account_service.getOpenTickets
-open_tickets.each { |ticket| puts "#{ticket['id']} - #{ticket['title']}" }
-
-# Now use the ticket service to get a each ticket (by ID) and a subset of the
-# 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_client["Ticket"]
+open_tickets.sort!{ |lhs, rhs| -(lhs.lastEditDate <=> rhs.lastEditDate) } 
 open_tickets.each do |ticket|
-  begin
-    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 #{exception}"
-  end
+  printf "#{ticket.id} - #{ticket.title}"
+
+  ticket.has_updates? ? printf("\t*\n") : printf("\n")
 end

data/examples/order_bare_metal_package.rb

@@ -0,0 +1,154 @@
+#
+# Copyright (c) 2014 SoftLayer Technologies, Inc. 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.
+#
+
+require 'rubygems'
+require 'softlayer_api'
+require 'pp'
+
+# This example walks through the process putting together an order for
+# a bare metal server using the SoftLayer::BareMetalServerOrder_Package class.
+#
+# The script uses verify_order to ensure the order constructed is
+# valid. If you actually wanted to place an order for a server
+# you would call place_order!
+
+# Here is the product order code boiled down to a single routine without
+# all the explaination found in the main body of code below. Skip down to
+# that code for a better explaination of the steps involved in ordering
+# a server.
+def tl_dr_version
+  client = SoftLayer::Client.new(
+    # :username => "joecustomer"              # enter your username here
+    # :api_key => "feeddeadbeefbadf00d..."   # enter your api key here
+  )
+
+  # Select a package
+  quad_intel_package = SoftLayer::ProductPackage.package_with_id(client, 32)
+
+  # Find required Categories and fill config_options with defaults
+  config_options = {}
+  required_categories = quad_intel_package.configuration.select { |category| category.required? }
+  required_categories.each { |required_category| config_options[required_category.categoryCode] = required_category.default_option }
+
+  # Provide a value for missing config categories
+  config_options['server'] = 1417 # price id of Quad Processor Quad Core Intel 7420 - 2.13GHz (Dunnington) - 4 x 6MB / 8MB cache
+
+  # With all the config options in place we can now construct the product order.
+  server_order = SoftLayer::BareMetalServerOrder_Package.new(quad_intel_package, client)
+  server_order.location = 'sng01'
+  server_order.hostname = 'sample'
+  server_order.domain = 'softlayerapi.org'
+  server_order.configuration_options = config_options
+
+  begin
+    server_order.verify()
+    puts "The Order appears to be OK"
+  rescue Exception => e
+    puts "Order didn't verify :-( #{e}"
+  end
+end
+
+begin
+  client = SoftLayer::Client.new(
+    # :username => "joecustomer"              # enter your username here
+    # :api_key => "feeddeadbeefbadf00d..."   # enter your api key here
+  )
+
+  # Servers are ordered from ProductPackages. We first get a list of all the
+  # Bare Metal Server packages and print that list along with the package IDs
+  puts "Bare Metal Server Packages:"
+  packages = SoftLayer::ProductPackage.bare_metal_server_packages(client)
+  packages.each { |package| puts "#{package.id}\t#{package.name}"}
+
+  # For this example, we'll assume that we've selected the a package
+  # with an id of 32 representing a "Quad Processor, Quad Core Intel"
+  quad_intel_package = SoftLayer::ProductPackage.package_with_id(32, client)
+
+  # Now we need to now what ProductItemCategories are required to
+  # configure a server in that package. This code prints out a table
+  # of the required category codes with a description of each
+  puts "\nRequired Categories for '#{quad_intel_package.name}':"
+  required_categories = quad_intel_package.configuration.select { |category| category.required? }
+  max_code_length = required_categories.inject(0) { |max_code_length, category| [category.categoryCode.length, max_code_length].max }
+  printf "%#{max_code_length}s\tCategory Description\n", "Category Code"
+  printf "%#{max_code_length}s\t--------------------\n", "-------------"
+  required_categories.each { |category| printf "%#{max_code_length}s\t#{category.name}\n", category.categoryCode}
+
+  # We will need to provide values for each of the required category codes in our
+  # configuration_options. Let's see what configuration options are available for
+  # just one of the categories... Say 'os'
+  os_category = quad_intel_package.category('os')
+  config_options = os_category.configuration_options
+  puts "\nConfiguration options in the 'os' category:"
+  config_options.each { |option| printf "%5s\t#{option.description}\n", option.price_id }
+
+  # For this example, we'll choose the first os option that contains the string 'CentOS 6'
+  # in its description
+  os_config_option = config_options.find { |option| option.description =~ /CentOS 6/ }
+
+  # Let's begin choosing configuration_options with the default options in each required category
+  # where they can be found. Read the description of ProductItemCategory#default_option carefully
+  # to avoid surprises!
+  config_options = {}
+  required_categories.each { |required_category| config_options[required_category.categoryCode] = required_category.default_option }
+
+  # print out descriptions of the the configuration options that were discovered
+  puts "\nConfiguration with default options:"
+  max_category_length = config_options.inject(0) { |max_category_length, pair| [pair[0].length, max_category_length].max }
+  config_options.each { |category, config_option| printf "%#{max_category_length}s\t#{config_option ? config_option.description : 'no default'}\n", category }
+
+  # Regardless of the default values... we know we want the os selection we discovered above:
+  config_options['os'] = os_config_option
+
+  # And we can customize the default config by providing selections for any config categories
+  # we are interested in
+  config_options.merge! ({
+    'server' => 1417, # price id of Quad Processor Quad Core Intel 7420 - 2.13GHz (Dunnington) - 4 x 6MB / 8MB cache
+    'port_speed' => 274 # 1 Gbps Public & Private Network Uplinks
+  })
+
+  # We have a configuration for the server, we also need a location for the new server.
+  # The package can give us a list of locations. Let's print out that list
+  puts "\nData Centers for '#{quad_intel_package.name}':"
+  quad_intel_package.datacenter_options.each { |location| puts "\t#{location}"}
+
+  # With all the config options in place we can now construct the product order.
+  server_order = SoftLayer::BareMetalServerOrder_Package.new(quad_intel_package, client)
+  server_order.datacenter = 'sng01'
+  server_order.hostname = 'sample'
+  server_order.domain = 'softlayerapi.org'
+  server_order.configuration_options = config_options
+
+  # The order should be complete... call verify_order to make sure it's OK.
+  # you'll either get back a filled-out order, or you will get an
+  # exception.  If you wanted to place the order, you would call 'place_order!' instead.
+  begin
+    server_order.verify()
+    puts "The Order appears to be OK"
+  rescue Exception => e
+    puts "Order didn't verify :-( #{e}"
+  end
+
+rescue Exception => exception
+  $stderr.puts "An exception occurred while trying to complete the SoftLayer API calls #{exception}"
+end
+

data/examples/order_virtual_server.rb

@@ -0,0 +1,85 @@
+#
+# Copyright (c) 2014 SoftLayer Technologies, Inc. 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.
+#
+
+require 'rubygems'
+require 'softlayer_api'
+require 'pp'
+
+begin
+  # This sample walks through the creation of a Virtual Server.
+  # It explores techniques for discovering what configuration options
+  # exist, puts together an order, then sends that order to
+  # SoftLayer for verification.
+
+  client = SoftLayer::Client.new(
+    # :username => "joecustomer"              # enter your username here
+    # :api_key => "feeddeadbeefbadf00d..."   # enter your api key here
+  )
+
+  # We begin by creating a VirtualServerOrder and filling out the hostname and domain
+  # attributes.
+  server_order = SoftLayer::VirtualServerOrder.new(client)
+  server_order.hostname = "server1"
+  server_order.domain = "ruby-api-test.org"
+
+  # We must tell the system in which datacenter we want our server created
+  # We can ask the class to give us a list of options:
+  puts SoftLayer::VirtualServerOrder.datacenter_options(client).inspect
+
+  # The list will look something like ["ams01", "dal01", "dal05",...
+  # Let's put our server in the 'dal05' (Dallas 5) datacenter
+  server_order.datacenter = 'dal05'
+
+  # The order must know how many computing cores we want in our virtual
+  # server.  Again we can ask the class for options.  The result will
+  # be something like [1, 2, 4, 8, 12, 16]
+  # 2 sounds like a good number of cores for our simple server
+  puts SoftLayer::VirtualServerOrder.core_options(client).inspect
+  server_order.cores = 2
+
+  # We must indicate how much memory the virtual server should have.
+  # Again we can query for options and select a good value
+  puts SoftLayer::VirtualServerOrder.memory_options(client).inspect
+  server_order.memory = 2 #GB
+
+  # Similarly we can choose an operating system for the server:
+  puts SoftLayer::VirtualServerOrder.os_reference_code_options(client).inspect
+  server_order.os_reference_code = 'CENTOS_6_64'
+
+  # Finally, in spite of the fact that our server is simple, we want it
+  # to have a blazing fast connection speed.  Let's look at the options and choose
+  # the fastest! (it's probably 1 Gbps)
+  server_order.max_port_speed = SoftLayer::VirtualServerOrder.max_port_speed_options(client).max
+
+  # The server order is now complete. This sample will ask it to verify itself with the
+  # SoftLayer ordering system, but a simple change from verify to place_order! would ask
+  # the system to provision the server (and charge it to our account)
+  begin
+    server_order.verify
+    puts "The server order is OK"
+  rescue Exception => e
+    puts "The server order failed verification :-( -- #{e}"
+  end
+rescue Exception => exception
+  $stderr.puts "An exception occurred while trying to complete the SoftLayer API calls #{exception}"
+end
+