SoftLayer provides a Perl-based API client that takes the heavy lifting out of making manual SOAP API calls. To use this API client, the following system requirements must be met:
Download the SoftLayer Perl API client from its project page on SoftLayer’s github profile. Once downloaded, extract the Perl API client to a directory local to your Perl project or into your Perl installation's @INC path.
Download the SoftLayer API Perl client
Once the API client is downloaded and installed the first thing to do is include the SoftLayer::API::SOAP module in your script. This file defines SoftLayer's client objects. You may have to add the module's parent directory to your @INC path before including the module. Add the parent directory using the following code:
use lib '/path/to/SoftLayer/'; use SoftLayer::API::SOAP;
Next, create a client object for the SoftLayer API service you wish to use. SoftLayer::API::SOAP->new() will take care of this for you and takes four parameters:
undef value if you're either working with the SoftLayer_Account service or are not working with a specific server, support ticket, invoice, or other object. This id creates an initialization parameter in your API call.use lib '/path/to/SoftLayer/'; use SoftLayer::API::SOAP; use strict; my $api_username = 'set me'; my $api_key = 'set me'; # Create a client to the SoftLayer_Account API service. my $client = SoftLayer::API::SOAP->new('SoftLayer_Account', undef, $api_username, $api_key); # Work directly with the SoftLayer_Hardware_Server record with the hardware id # 1234. #my $server_id = 1234; #my $client = SoftLayer::API::SOAP->new('SoftLayer_Hardware_Server', $server_id, $api_username, $api_key);
Once your API client object ($client) is ready, call a SoftLayer API method as if it were local to your client object. Assign the result of your API call to a variable to get the call's result. Complex type objects are returned as hashes blessed as your call's return type. Likewise, use hashes, hashes containing hashes, or hashes containing arrays if you need to pass complex type parameters to your API calls. For example:
use lib '/path/to/SoftLayer/'; use SoftLayer::API::SOAP; use strict; my $api_username = 'set me'; my $api_key = 'set me'; my $domain_id = 1234; my $client = SoftLayer::API::SOAP->new('SoftLayer_Dns_Domain', $domain_id, $api_username, $api_key); # Create a new A record in a domain. my $new_record = $client->createARecord('myhost', '127.0.0.1', 86400); print 'New A record id: ' . $new_record->{id}; # Create a new domain record. # # This requires an API client with an undef id, and use a hash with an array to model # our new domain. $client = SoftLayer::API::SOAP->new('SoftLayer_Dns_Domain', undef, $api_username, $api_key); my $domain = { 'name' => 'example.org', 'resourceRecords' => [ { 'host' => '@', 'data' => '127.0.0.1', 'type' => 'a', } ] }; my $new_domain = $client->createObject($domain); print 'New domain id: ' . $new_domain->{id}; If you wish, you can declare your client object and make an API call on a single line. The following code outlines this scenario: use lib '/path/to/SoftLayer/'; use SoftLayer::API::SOAP; use strict; my $api_username = 'set me'; my $api_key = 'set me'; my $account = SoftLayer::API::SOAP->new('SoftLayer_Account', undef, $api_username, $api_key)->getObject();
Use a nested hash variable to create an object mask to your API call. Define the relational properties you wish to retrieve as hash keys. If you are retrieving child properties, define a nested hash for your child property. Otherwise, define an empty hash as your key's value. Bind your object mask to your API client with the setObjectMask() method. 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:
use lib '/path/to/SoftLayer/'; use SoftLayer::API::SOAP; use strict; my $api_username = 'set me'; my $api_key = 'set me'; my $client = SoftLayer::API::SOAP->new('SoftLayer_Account', undef, $api_username, $api_key); # 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. my $object_mask = { 'hardware' => { 'operatingSystem' => { 'passwords' => {}, }, 'networkComponents' => {}, 'datacenter' => {}, 'processorCount' => {}, } }; $client->setObjectMask($object_mask); my $hardware = $client->getHardware();
When calling data, especially queries that involve pulling snippets of information from larger groups, utilizing result limits will greatly decrease your wait time for the return.
Limit the number of results in your API call with your client object's setResultLimit() method. This method takes two parameters:
The code below provides an example of using result limits in y our API call.
use lib '/path/to/SoftLayer/'; use SoftLayer::API::SOAP; use strict; my $api_username = 'set me'; my $api_key = 'set me'; my $client = SoftLayer::API::SOAP->new('SoftLayer_Account', undef, $api_username, $api_key); # Retrieve our first two open support tickets. $client->setResultLimit(2); $tickets = $client->getOpenTickets();
If a SOAP fault was thrown by your SoftLayer API call then your client object will have fault and faultstring properties populated. Check the fault property after making an API call for effective error handling. If there was an error in your call, the faultstring property contains the error returned by the SoftLayer API. The following script contains an example of such error:
use lib '/path/to/SoftLayer/'; use SoftLayer::API::SOAP; use strict; my $api_username = 'set me'; my $api_key = 'an incorrect key'; $client = SoftLayer::API::SOAP->new('SoftLayer_Account', null, $api_username, $api_key); # Exit the script with the message: # "Unable to retrieve account information: Invalid API key" my $account = $client->getObject(); if ($account->fault) { die 'Unable to retrieve account information: ' . $account->faultstring; }