June 20, 2011


Using the SoftLayer API with python


SoftLayer, an IBM company, provides a Python-based API package that takes the heavy lifting out of making manual XML-RPC API calls. Our Python-based API requires a minimum of Python 2.6 To install the Python package into your Python installation’s site-packages directory, run the following command:

pip install softlayer

Refer to our Python bindings documentation for more install options.

Making API Calls

Once the API client is installed, the first thing to do is import the SoftLayer package in your script. Use the following line to do that:

import SoftLayer

Next, we need to create a client object. The code snippet below provides an example of setting up an API client:

import SoftLayer
client = SoftLayer.Client(username='YOUR_USERNAME', api_key='YOUR_API_KEY')

Once your API client object is ready, we can make calls with it. Here's how to get the account details for the current account. The call takes no parameters and doesn't require an id so it's the natural starting point.


Here's how you'd create a new CloudLayer Computing Instance, which requires the use of the Virtual Guest record. The virtual guest record is a complex type, which is passed in as a Python dictionary.

    'hostname': 'myhostname',
    'domain': 'example.org',
    'startCpus': 1,
    'maxMemory': 1024,
    'hourlyBillingFlag': 'true',
    'operatingSystemReferenceCode': 'UBUNTU_LATEST',
    'localDiskFlag': 'false',
    'datacenter': {'name': 'dal09'}

Here's how you'd create a new domain zone on our DNS service.

new_domain = client['Dns_Domain'].createObject({{
    'name' : 'example.org',
    'resourceRecords' => [
            'host' : '@',
            'data' : '',
            'type' : 'a',

Now that we have a zone created for our domain, the following example shows how you add an A record in that zone after the fact. Note how parameters are passed in as positional arguments and the required domain id is passed using the id keyword argument. This example uses the domain id that was created in the last call.

new_record = client['Dns_Domain'].createARecord('myhost', '', 86400, id=new_domain['id'])
print("New A record id: %", new_record['id'])

Using Object Masks

Object masks allow you to control what attributes are returned in each call. It can be used to dig much deeper into an object to get specific

# Because of the object mask that we're using we will retrieve the following
# for each server:
# * operating system passwords
# * all network components
# * the datacenter the server is located in
# * the number of processors
object_mask = 'operatingSystem.passwords, networkComponents, datacenter, processorCount'
hardware = client['Account'].getHardware(mask=object_mask)

Using Result Limits

The SoftLayer API allows limits to the number of returned results and offsets to better control the amount of data returned on certain calls. Below is an example showing pagination.

client['Account'].getVirtualGuests(limit=10, offset=0)  # Page 1
client['Account'].getVirtualGuests(limit=10, offset=10)  # Page 2

Error Handling

Errors that happen when making SoftLayer API calls appear as exceptions. The following script provides an example of how an API error can be handled. In this case we simply print out the details of the error and exit:

client = SoftLayer.Client(username='invalid', api_key='invalid')
    account = client['Account'].getObject()
except SoftLayer.SoftLayerAPIError as e:
    print("Unable to retrieve account information faultCode=%s, faultString=%s"
          % (e.faultCode, e.faultString))
# This should output:
# Unable to retrieve account information faultCode=SoftLayer_Exception, faultString=Invalid API token.


Everything above this section has addressed how to use the base API client to interact with the XML-RPC API that's documented here on SLDN. The Python bindings also have managers that abstract away some functionality from direct API calls. For reference of all available managers, refer to our API Python Client documentation.

Creating a new CloudLayer Computing Instance, as we did above, would look something like this using our Python API Client managers (unsure if Python API Client managers is right, but feel free to replace that with what is, if you need to):

import SoftLayer
client = SoftLayer.Client(username='YOUR_USERNAME', api_key='YOUR_API_KEY')
cci_manager = SoftLayer.CCIManager(client)

Below is an example of listing hardware servers with more than 8 gigabytes of memory in the dal05 datacenter.

hardware_manager = SoftLayer.HardwareManager(client)
hardware = hardware_manager.list_hardware(datacenter='dal05', memory='> 8')

The managers are a good way of being introduced to a smaller subset of the API and provide a reference for doing common tasks.

More Resources

The Python bindings are publicly developed on GitHub. New features are developed and bugs are reported through GitHub's Integrated Issue Tracking. The full documentation for SoftLayer API Python client is available here. The bindings also have a command-line interface that hasn't been mentioned here. You can find more information on that in its full documentation site.


If this article contains any error, or leaves any of your questions unanswered, please help us out by opening up a github issue.
Open an issue