API Documentation

This is the primary API client to make API calls. It deals with constructing and executing XML-RPC calls against the SoftLayer API. Below are some links that will help to use the SoftLayer API.

>>> import SoftLayer
>>> client = SoftLayer.create_client_from_env(username="username", api_key="api_key")
>>> resp = client.call('Account', 'getObject')
>>> resp['companyName']
'Your Company'

Getting Started

You can pass in your username and api_key when creating a SoftLayer client instance. However, you can also set these in the environmental variables ‘SL_USERNAME’ and ‘SL_API_KEY’.

Creating a client instance by passing in the username/api_key:

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

Creating a client instance with environmental variables set:

$ export SL_USERNAME=YOUR_USERNAME
$ export SL_API_KEY=YOUR_API_KEY
$ python
>>> import SoftLayer
>>> client = SoftLayer.create_client_from_env()

Below is an example of creating a client instance with more options. This will create a client with the private API endpoint (only accessible from the SoftLayer private network) and a timeout of 4 minutes.

client = SoftLayer.create_client_from_env(username='YOUR_USERNAME',
                                          api_key='YOUR_API_KEY'
                                          endpoint_url=SoftLayer.API_PRIVATE_ENDPOINT,
                                          timeout=240)

Managers

For day-to-day operation, most users will find the managers to be the most convenient means for interacting with the API. Managers abstract a lot of the complexities of using the API into classes that provide a simpler interface to various services. These are higher-level interfaces to the SoftLayer API.

from SoftLayer import VSManager, Client
client = Client(...)
vs = VSManager(client)
vs.list_instances()
[...]

Available managers:

If you need more power or functionality than the managers provide, you can make direct API calls as well.

Making API Calls

For full control over your account and services, you can directly call the SoftLayer API. The SoftLayer API client for python leverages SoftLayer’s XML-RPC API. It supports authentication, object masks, object filters, limits, offsets, and retrieving objects by id. The following section assumes you have an initialized client named ‘client’.

The best way to test our setup is to call the getObject method on the SoftLayer_Account service.

client.call('Account', 'getObject')

For a more complex example we’ll retrieve a support ticket with id 123456 along with the ticket’s updates, the user it’s assigned to, the servers attached to it, and the datacenter those servers are in. To retrieve our extra information using an object mask.

Retrieve a ticket using object masks.

ticket = client.call('Ticket', 'getObject',
    id=123456, mask="updates, assignedUser, attachedHardware.datacenter")

Now add an update to the ticket with Ticket.addUpdate. This uses a parameter, which translate to positional arguments in the order that they appear in the API docs.

update = client.call('Ticket', 'addUpdate', {'entry' : 'Hello!'}, id=123456)

Let’s get a listing of virtual guests using the domain example.com

client.call('Account', 'getVirtualGuests',
    filter={'virtualGuests': {'domain': {'operation': 'example.com'}}})

This call gets tickets created between the beginning of March 1, 2013 and March 15, 2013. More information on Object Filters.

NOTE

The value field for startDate and endDate is in [], if you do not put the date in brackets the filter will not work.

client.call('Account', 'getTickets',
    filter={
        'tickets': {
            'createDate': {
                'operation': 'betweenDate',
                'options': [
                    {'name': 'startDate', 'value': ['03/01/2013 0:0:0']},
                    {'name': 'endDate', 'value': ['03/15/2013 23:59:59']}
                ]
            }
        }
    }
)

SoftLayer’s XML-RPC API also allows for pagination.

from pprint import pprint

page1 = client.call('Account', 'getVirtualGuests', limit=10, offset=0)  # Page 1
page2 = client.call('Account', 'getVirtualGuests', limit=10, offset=10)  # Page 2

#Automatic Pagination (v5.5.3+), default limit is 100
result = client.call('Account', 'getVirtualGuests', iter=True, limit=10)
pprint(result)

# Using a python generator, default limit is 100
results = client.iter_call('Account', 'getVirtualGuests', limit=10)
for result in results:
    pprint(result)
NOTE

client.call(iter=True) will pull all results, then return. client.iter_call() will return a generator, and only make API calls as you iterate over the results.

Here’s how to create a new Cloud Compute Instance using SoftLayer_Virtual_Guest.createObject. Be warned, this call actually creates an hourly virtual server so this will have billing implications.

client.call('Virtual_Guest', 'createObject', {
        'hostname': 'myhostname',
        'domain': 'example.com',
        'startCpus': 1,
        'maxMemory': 1024,
        'hourlyBillingFlag': 'true',
        'operatingSystemReferenceCode': 'UBUNTU_LATEST',
        'localDiskFlag': 'false'
    })

Debugging

If you ever need to figure out what exact API call the client is making, you can do the following:

NOTE the print_reproduceable method produces different output for REST and XML-RPC endpoints. If you are using REST, this will produce a CURL call. IF you are using XML-RPC, it will produce some pure python code you can use outside of the SoftLayer library.

# Setup the client as usual
client = SoftLayer.Client()
# Create an instance of the DebugTransport, which logs API calls
debugger = SoftLayer.DebugTransport(client.transport)
# Set that as the default client transport
client.transport = debugger
# Make your API call
client.call('Account', 'getObject')

# Print out the reproduceable call
for call in client.transport.get_last_calls():
    print(client.transport.print_reproduceable(call))

Dealing with KeyError Exceptions

One of the pain points in dealing with the SoftLayer API can be handling issues where you expected a property to be returned, but none was.

The hostname property of a SoftLayer_Billing_Item is a good example of this.

For example.

# Uses default username and apikey from ~/.softlayer
client = SoftLayer.create_client_from_env()
# iter_call returns a python generator, and only makes another API call when the loop runs out of items.
result = client.iter_call('Account', 'getAllBillingItems', iter=True, mask="mask[id,hostName]")
print("Id, hostname")
for item in result:
    # will throw a KeyError: 'hostName' exception on certain billing items that do not have a hostName
    print("{}, {}".format(item['id'], item['hostName']))

The Solution

Using the python dictionary’s .get() is great for non-nested items.

::

print(“{}, {}”.format(item.get(‘id’), item.get(‘hostName’)))

Otherwise, this SDK provides a util function to do something similar. Each additional argument passed into utils.lookup will go one level deeper into the nested dictionary to find the item requested, returning None if a KeyError shows up.

::

itemId = SoftLayer.utils.lookup(item, ‘id’) itemHostname = SoftLayer.utils.lookup(item, ‘hostName’) print(“{}, {}”.format(itemId, itemHostname))

API Reference

SoftLayer Python API Client

SoftLayer API bindings

Usage:

>>> import SoftLayer
>>> client = SoftLayer.create_client_from_env(username="username",
                                              api_key="api_key")
>>> resp = client.call('Account', 'getObject')
>>> resp['companyName']
'Your Company'
license

MIT, see LICENSE for more details.

class SoftLayer.BaseClient(auth=None, transport=None, config_file=None)[source]

Base SoftLayer API client.

Parameters
  • auth – auth driver that looks like SoftLayer.auth.AuthenticationBase

  • transport – An object that’s callable with this signature: transport(SoftLayer.transports.Request)

authenticate_with_password(username, password, security_question_id=None, security_question_answer=None)[source]

Performs Username/Password Authentication

Parameters
  • username (string) – your SoftLayer username

  • password (string) – your SoftLayer password

  • security_question_id (int) – The security question id to answer

  • security_question_answer (string) – The answer to the security question

call(service, method, *args, **kwargs)[source]

Make a SoftLayer API call.

Parameters
  • method – the method to call on the service

  • *args – (optional) arguments for the remote call

  • id – (optional) id for the resource

  • mask – (optional) object mask

  • filter (dict) – (optional) filter dict

  • headers (dict) – (optional) optional XML-RPC headers

  • compress (boolean) – (optional) Enable/Disable HTTP compression

  • raw_headers (dict) – (optional) HTTP transport headers

  • limit (int) – (optional) return at most this many results

  • offset (int) – (optional) offset results by this many

  • iter (boolean) – (optional) if True, returns a generator with the results

  • verify (bool) – verify SSL cert

  • cert – client certificate path

Usage:
>>> import SoftLayer
>>> client = SoftLayer.create_client_from_env()
>>> client.call('Account', 'getVirtualGuests', mask="id", limit=10)
[...]
iter_call(service, method, *args, **kwargs)[source]

A generator that deals with paginating through results.

Parameters
  • service – the name of the SoftLayer API service

  • method – the method to call on the service

  • limit (integer) – result size for each API call (defaults to 100)

  • *args – same optional arguments that Service.call takes

  • **kwargs – same optional keyword arguments that Service.call takes

class SoftLayer.BasicAuthentication(username, api_key)[source]

Token-based authentication class.

Parameters
  • str (api_key) – a user’s username

  • str – a user’s API key

get_request(request)[source]

Sets token-based auth headers.

SoftLayer.Client(**kwargs)[source]

Get a SoftLayer API Client using environmental settings.

Deprecated in favor of create_client_from_env()

exception SoftLayer.SoftLayerAPIError(fault_code, fault_string, *args)[source]

SoftLayerAPIError is an exception raised during API errors.

Provides faultCode and faultString properties.

exception SoftLayer.SoftLayerError[source]

The base SoftLayer error.

class SoftLayer.SoftLayerListResult(items=None, total_count=0)[source]

A SoftLayer API list result.

total_count

total count of items that exist on the server. This is useful when paginating through a large list of objects.

SoftLayer.create_client_from_env(username=None, api_key=None, endpoint_url=None, timeout=None, auth=None, config_file=None, proxy=None, user_agent=None, transport=None, verify=True)[source]

Creates a SoftLayer API client using your environment.

Settings are loaded via keyword arguments, environemtal variables and config file.

Parameters
  • username – an optional API username if you wish to bypass the package’s built-in username

  • api_key – an optional API key if you wish to bypass the package’s built in API key

  • endpoint_url – the API endpoint base URL you wish to connect to. Set this to API_PRIVATE_ENDPOINT to connect via SoftLayer’s private network.

  • proxy – proxy to be used to make API calls

  • timeout (integer) – timeout for API requests

  • auth – an object which responds to get_headers() to be inserted into the xml-rpc headers. Example: BasicAuthentication

  • config_file – A path to a configuration file used to load settings

  • user_agent – an optional User Agent to report when making API calls if you wish to bypass the packages built in User Agent string

  • transport – An object that’s callable with this signature: transport(SoftLayer.transports.Request)

  • verify (bool) – decide to verify the server’s SSL/TLS cert. DO NOT SET TO FALSE WITHOUT UNDERSTANDING THE IMPLICATIONS.

Usage:

>>> import SoftLayer
>>> client = SoftLayer.create_client_from_env()
>>> resp = client.call('Account', 'getObject')
>>> resp['companyName']
'Your Company'