Share this article:

Python

Table of contents

A Note Regarding Python 3
Making API Calls
Using Object Masks
Using Result Limits
Error Handling
Referenced API Components
External Links

SoftLayer provides a Python-based API package that takes the heavy lifting out making manual XML-RPC API calls. It requires a minimum of Python 2.4 installed.

Download the SoftLayer Python API package from its project page on SoftLayer's github profile. Change directory to your downloaded project root directory and run the following command to install this package into your Python installation’s site-packages directory:

python ./setup.py install

Add --help to the end of this command to view installation options.

A Note Regarding Python 3

The examples on this page are written in Python 2.x syntax. For compatibility with Python 3, use parenthesis in print() statements and use the as keyword when handling exceptions. For instance, lines such as:

print "New A record id: %", new_record{'id'}

become:

print("New A record id: %", new_record{'id'})

and lines such as:

except Exception, e:

become:

except Exception as e:

Making API Calls

Once the API client is downloaded and installed, the first thing to do is import the SoftLayer.API package in your script. This module defines SoftLayer's client objects. Use the following code to complete this task:

import SoftLayer.API

Next, create a client object for the SoftLayer API service you wish to use. The SoftLayer.API.Client module takes care of this for you. Its constructor takes four parameters:

The name of the service you wish to call
An optional ID number of the specific object you wish to work with
- Pass the None object 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.
Your API username
Your API key

The code snippet below provides an example of making an API call, utilizing the previously outlined parameters:

import SoftLayer.API
 
api_username = 'set me'
api_key = 'set me'
 
# Create a client to the SoftLayer_Account API service.
client = SoftLayer.API.Client('SoftLayer_Account', None, api_username, api_key)
 
 
# Work directly with the SoftLayer_Hardware_Server record with the hardware id 
# 1234.
server_id = 1234
client = SoftLayer.API.Client('SoftLayer_Hardware_Server', server_id, api_username, api_key)

Once your API client object 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.
:Note: Complex type objects are returned as dictionary objects. Define dictionary objects if you need to pass complex type parameters to your API calls.

import SoftLayer.API
 
api_username = 'set me'
api_key = 'set me'
domain_id = 1234
 
client = SoftLayer.API.Client('SoftLayer_Dns_Domain', domain_id, api_username, api_key)
 
# Create a new A record in a domain.
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 None id, and use a hash with an array to model 
# our new domain.
client = SoftLayer.API.Client('SoftLayer_Dns_Domain', None, api_username, api_key)
 
domain = {
    'name' : 'example.org',
    'resourceRecords' => [
        {
            'host' : '@',
            'data' : '127.0.0.1',
            'type' : 'a',
        }
    ]
}
 
new_domain = client.createObject(domain)
 
print "New domain id: %", new_domain{'id'}

Using Object Masks

Use dictionaries to create an object mask to your API call. Define the relational properties you wish to retrieve in your dictionary's key names. If you're retrieving child properties then define a nested dictionary for your child property, otherwise define an empty dictionary as your key's value. Bind your object mask to your API client with theset_object_mask() method.

This example retrieves the following information:
*An account's physical hardware records
*The hardware's operating system record
*Operating system passwords
*Network components
*Datacenter in which the hardware is located in
*Number of processors in each hardware

import SoftLayer.API
 
api_username = 'set me'
api_key = 'set me'
 
client = SoftLayer.API.Client('SoftLayer_Account', None, 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.
object_mask = {
    'hardware' : {
        'operatingSystem' : {
            'passwords' : {},
        },
        'networkComponents' : {},
        'datacenter' : {},
        'processorCount' : {},
    }
}
 
client.set_object_mask(object_mask)
 
hardware = client.getHardware()

Using Result Limits

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 set_result_limit() method. This method takes two parameters:
*The number of results to limit your call.
*An optional offset to begin your result set.

The code below provides an example of using result limits in y our API call:

import SoftLayer.API
 
api_username = 'set me'
api_key = 'set me'
 
client = SoftLayer.API.Client('SoftLayer_Account', None, api_username, api_key)
 
# Retrieve our first two open support tickets.
client.set_result_limit(2)
 
tickets = client.getOpenTickets()

Error Handling

SoftLayer API call errors are thrown by the Python client as exceptions. Place calls to the SoftLayer API inside try/catch blocks to ensure proper handling. The following script provides an example of such error:

import SoftLayer.API
 
api_username = 'set me'
api_key = 'set me'
 
client = SoftLayer.API.Client('SoftLayer_Account', None, api_username, api_key)
 
# Exit the script with the message:
# "Unable to retrieve account information: Invalid API key"
try:
    account = client.getObject()
except Exception, e:
    print "Unable to retrieve account information: %", e

Referenced API Components

External Links

*Python Programming Language
*The SoftLayer API Python Client at github

Was this helpful?

Yes

Primary links

Key Articles