Merge pull request #19 from softlayer/server_model

Introduces the SoftLayer object framework including Virtual Servers, Bare Metal Servers, and rudimentary Tickets.

Author: SLsthompson

.gitignore

@@ -4,3 +4,5 @@
 .bundle/
 log/
 internal_examples/
+doc/
+Gemfile.lock

.travis.yml

@@ -1,7 +1,7 @@
 language: ruby
 rvm:
+  - "2.1.2"
   - "2.1.1"
-  - "2.1.0"
   - "2.0.0"
   - "1.9.3"
   - "1.9.2"

CHANGELOG.textile

@@ -1,3 +1,6 @@
+*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
 
@@ -9,7 +12,7 @@ The @result_offset@ API filter has been removed.
 * 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.
+* 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.

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.
 

examples/account_info.rb

@@ -26,13 +26,16 @@
 
 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}"

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

examples/create_ticket.rb

@@ -24,33 +24,44 @@
 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

examples/open_tickets.rb

@@ -24,27 +24,22 @@
 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