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.
The Ruby client's source code is available on SoftLayer's github project.
To begin using the Ruby client, you will have to create an instance of the SoftLayer::Service class for each the API 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.
That instance will have to know your API authentication information 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.
The SoftLayer Ruby Client makes use of three global variables, in the SoftLayer name space, related to creating instances of the SoftLayer::Service class:
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:
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:
$SL_API_USERNAME = "set me"; $SL_API_KEY = "set me" account_service = SoftLayer::Service.new("SoftLayer_Account")
Note that the endpoint URL is not specified. The default endpoint URL is set to the API_PUBLIC_ENDPOINT
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:
:username The username used to authenticate with the server. :api_key The API key used to authenticate with the server. :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:
account_service = SoftLayer::Service.new("SoftLayer_Account", :username => "set me", :api_key => "set me", :endpoint_url => API_PRIVATE_ENDPOINT)
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:
open_tickets = account_service.getOpenTicketsIf 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 SoftLayer_Dns_Domain::createObject.
#authentication information will be found in the global variables domain_service = SoftLayer::Service.new("SoftLayer_Dns_Domain") new_domain = domain_service.createObject( { "name" => "example.org", "resourceRecords" => [ { "host" => "@", "data" => "127.0.0.1", "type" => "a" } ] }) puts "New domain id: #{new_domain.id}"
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:
ticket_of_interest = ticket_service.object_with_id(123456).getObject
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:
ticket_service = SoftLayer::Service.new("SoftLayer_Ticket") begin ticket_ref = ticket_service.object_with_id(98765) ticket = ticket_ref.object_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
The code creates a variable named ticket_ref which refers to ticket 98765 through the ticket_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.
Use hashes to create an Using Object Masks in the SoftLayer API to your API call. Define the relational properties you wish to retrieve in your hash key names. If you're retrieving child properties then define a nested hash for your child property, otherwise define an empty string as your key's value. Bind your object mask to your API client with the object_mask() method. object_mask() creates a new API service reference, much like the object_with_id() method. You can either apply your object mask on the same line as your API call or create new API service reference with object_Mask() and call your API method on its result.
This example retrieves an account's physical hardware records along with that hardware's operating system record, operating system passwords, network components, the datacenter the hardware is located in, and the number of processors in each hardware:
require 'rubygems' require 'softlayer_api' account_service = SoftLayer::Service.new("SoftLayer_Account", :username => "set me", :api_key => "set me") # Retrieve items related to hardware. # # Operating system, operating system passwords, all network components, the # datacenter the server is located in, and the number of processors in each # server. object_mask = { "hardware" => { "operatingSystem" => { "passwords" => "", }, "networkComponents" => "", "datacenter" => "", "processorCount" => "" } } account = account_service.object_mask(object_mask).getHardware # This will also work: masked_service = account_service.object_mask(object_mask) account = masked_service.getHardware
SoftLayer API call errors are thrown by the Ruby client as exception objects. Place calls to the SoftLayer API inside begin/rescue blocks to ensure proper handling.
require 'rubygems' require 'softlayer_api' account_service = SoftLayer::Service.new("SoftLayer_Account", :username => "set me", :api_key => "incorrect password") # Exit the script with the message: # "Unable to retrieve account information: Access Denied" begin account = account_service.getObject rescue Exception => exception puts "Unable to retrieve account information: #{exception}" end