Developer Interface

This is the primary API client to make API calls. It deals with constructing and executing XML-RPC calls against the SoftLayer API.

Getting Started

You can pass in your username and api_key when creating a SoftLayer client instance. However, you can 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.Client(username='YOUR_USERNAME', api_key='YOUR_API_KEY')

Creating a client instance with environmental variables set:

# env variables
# SL_USERNAME = YOUR_USERNAME
# SL_API_KEY = YOUR_API_KEY
import SoftLayer
client = SoftLayer.Client()

Below is an example of creating a client instance with more options. This will create a client with the private API endpoint (only accessable from the SoftLayer network), a timeout of 2 minutes, and with verbose mode on (prints out more than you ever wanted to know about the HTTP requests to stdout).

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

Making API Calls

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 a initialized client named ‘client’.

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

client['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.

Retreive a ticket using Object Masks.

ticket = client['Ticket'].getObject(
    id=123456, mask="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['Ticket'].addUpdate({'entry' : 'Hello!'}, id=123456)

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

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

This call gets tickets created between the beginning of March 1, 2013 and March 15, 2013.

client['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.

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

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

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

API Reference

class SoftLayer.Client(service_name=None, id=None, username=None, api_key=None, endpoint_url=None, timeout=None, auth=None)

A SoftLayer API client.

Parameters:
  • service_name – the name of the SoftLayer API service to query
  • id (integer) – an optional object ID if you’re instantiating a particular SoftLayer_API object. Setting an ID defines this client’s initialization parameter.
  • 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.
  • timeout (integer) – timeout for API requests
  • auth – an object which responds to get_headers() to be inserted into the xml-rpc headers. Example: BasicAuthentication

Usage:

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

Get a SoftLayer Service.

Parameters:name – The name of the service. E.G. Account
Usage:
>>> client = SoftLayer.Client()
>>> client['Account']
<Service: Account>
authenticate_with_password(username, password, security_question_id=None, security_question_answer=None)

Performs Username/Password Authentication and gives back an auth handler to use to create a client that uses token-based auth.

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)

Make a SoftLayer API call

Parameters:
  • service – the name of the SoftLayer API service
  • method – the method to call on the service
  • *args – same optional arguments that Service.call takes
  • **kwargs – same optional keyword arguments that Service.call takes
  • service – the name of the SoftLayer API service
Usage:
>>> client = SoftLayer.Client()
>>> client['Account'].getVirtualGuests(mask="id", limit=10)
[...]
iter_call(service, method, chunk=100, limit=None, offset=0, *args, **kwargs)

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
  • chunk (integer) – result size for each API call
  • *args – same optional arguments that Service.call takes
  • **kwargs – same optional keyword arguments that Service.call takes
class SoftLayer.API.Service(client, name)[source]
__call__(name, *args, **kwargs)

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
  • 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
Usage:
>>> client['Account'].getVirtualGuests(mask="id", limit=10)
[...]
call(name, *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
  • 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
Usage:
>>> client['Account'].getVirtualGuests(mask="id", limit=10)
[...]
iter_call(name, *args, **kwargs)[source]

A generator that deals with paginating through results.

Parameters:
  • method – the method to call on the service
  • chunk (integer) – result size for each API call
  • *args – same optional arguments that Service.call takes
  • **kwargs – same optional keyword arguments that Service.call takes
Usage:
>>> gen = client['Account'].getVirtualGuests(iter=True)
>>> for virtual_guest in gen:
...     virtual_guest['id']
...
1234
4321

SoftLayer.exceptions

Exceptions used throughout the library

copyright:
  1. 2013, SoftLayer Technologies, Inc. All rights reserved.
license:

BSD, see LICENSE for more details.

exception SoftLayer.exceptions.ApplicationError(faultCode, faultString, *args)[source]

Application Error

exception SoftLayer.exceptions.DNSZoneNotFound[source]
exception SoftLayer.exceptions.InternalError(faultCode, faultString, *args)[source]
exception SoftLayer.exceptions.InvalidCharacter(faultCode, faultString, *args)[source]
exception SoftLayer.exceptions.InvalidMethodParameters(faultCode, faultString, *args)[source]
exception SoftLayer.exceptions.MethodNotFound(faultCode, faultString, *args)[source]
exception SoftLayer.exceptions.NotWellFormed(faultCode, faultString, *args)[source]
exception SoftLayer.exceptions.ParseError(faultCode, faultString, *args)[source]

Parse Error

exception SoftLayer.exceptions.RemoteSystemError(faultCode, faultString, *args)[source]

System Error

exception SoftLayer.exceptions.ServerError(faultCode, faultString, *args)[source]

Server Error

exception SoftLayer.exceptions.SoftLayerAPIError(faultCode, faultString, *args)[source]

SoftLayerAPIError is an exception raised whenever an error is returned from the API.

Provides faultCode and faultString properties.

exception SoftLayer.exceptions.SoftLayerError[source]

The base SoftLayer error.

exception SoftLayer.exceptions.SpecViolation(faultCode, faultString, *args)[source]
exception SoftLayer.exceptions.TransportError(faultCode, faultString, *args)[source]

Transport Error

exception SoftLayer.exceptions.Unauthenticated[source]

Unauthenticated

exception SoftLayer.exceptions.UnsupportedEncoding(faultCode, faultString, *args)[source]

Backwards Compatibility

If you’ve been using the older Python client (<2.0), you’ll be happy to know that the old API is still currently working. However, you should deprecate use of the old stuff. Below is an example of the old API converted to the new one.

SoftLayer.deprecated

This is where deprecated APIs go for their eternal slumber

copyright:
  1. 2013, SoftLayer Technologies, Inc. All rights reserved.
license:

BSD, see LICENSE for more details.

class SoftLayer.deprecated.DeprecatedClientMixin(id=None, username=None, api_key=None, **kwargs)[source]

This mixin is to be used in SoftLayer.Client so all of these methods should be available to the client but are all deprecated.

add_header(name, value)[source]

Set a SoftLayer API call header.

Parameters:
  • name – the header name
  • value – the header value

Deprecated since version 2.0.0.

add_raw_header(name, value)[source]

Set HTTP headers for API calls.

Parameters:
  • name – the header name
  • value – the header value

Deprecated since version 2.0.0.

remove_header(name)[source]

Remove a SoftLayer API call header.

Parameters:name – the header name

Deprecated since version 2.0.0.

set_authentication(username, api_key)[source]

Set user and key to authenticate a SoftLayer API call.

Use this method if you wish to bypass the API_USER and API_KEY class constants and set custom authentication per API call.

See https://manage.softlayer.com/Administrative/apiKeychain for more information.

Parameters:
  • username – the username to authenticate with
  • api_key – the user’s API key

Deprecated since version 2.0.0.

set_init_parameter(id)[source]

Set an initialization parameter header.

Initialization parameters instantiate a SoftLayer API service object to act upon during your API method call. For instance, if your account has a server with ID number 1234, then setting an initialization parameter of 1234 in the SoftLayer_Hardware_Server Service instructs the API to act on server record 1234 in your method calls.

See http://sldn.softlayer.com/article/Using-Initialization-Parameters-SoftLayer-API # NOQA for more information.

Parameters:id – the ID of the SoftLayer API object to instantiate

Deprecated since version 2.0.0.

set_object_mask(mask)[source]

Set an object mask to a SoftLayer API call.

Use an object mask to retrieve data related your API call’s result. Object masks are skeleton objects, or strings that define nested relational properties to retrieve along with an object’s local properties. See http://sldn.softlayer.com/article/Using-Object-Masks-SoftLayer-API for more information.

Parameters:mask – the object mask you wish to define

Deprecated since version 2.0.0.

set_result_limit(limit, offset=0)[source]

Set a result limit on a SoftLayer API call.

Many SoftLayer API methods return a group of results. These methods support a way to limit the number of results retrieved from the SoftLayer API in a way akin to an SQL LIMIT statement.

Parameters:
  • limit – the number of results to limit a SoftLayer API call to
  • offset – An optional offset at which to begin a SoftLayer API call’s returned result

Deprecated since version 2.0.0.

import SoftLayer.API
client = SoftLayer.API.Client('SoftLayer_Account', None, 'username', 'api_key')
client.set_object_mask({'ipAddresses' : None})
client.set_result_limit(10, offset=10)
client.getObject()

... changes to ...

import SoftLayer
client = SoftLayer.Client(username='username', api_key='api_key')
client['Account'].getObject(mask="mask[ipAddresses]", limit=10, offset=0)

Deprecated APIs

Below are examples of how the old usages to the new API.

Importing the module

# Old
import SoftLayer.API

# New
import SoftLayer

Creating a client instance

# Old
client = SoftLayer.API.Client('SoftLayer_Account', None, 'username', 'api_key')

# New
client = SoftLayer.Client(username='username', api_key='api_key')
service = client['Account']

Making an API call

# Old
client = SoftLayer.API.Client('SoftLayer_Account', None, 'username', 'api_key')
client.getObject()

# New
client = SoftLayer.Client(username='username', api_key='api_key')
client['Account'].getObject()

# Optionally
service = client['Account']
service.getObject()

Setting Object Mask

# Old
client.set_object_mask({'ipAddresses' : None})

# New
client['Account'].getObject(mask="mask[ipAddresses]")

Using Init Parameter

# Old
client.set_init_parameter(1234)

# New
client['Account'].getObject(id=1234)

Setting Result Limit and Offset

# Old
client.set_result_limit(10, offset=10)

# New
client['Account'].getObject(limit=10, offset=10)

Adding Additional Headers

# Old
# These headers are persisted accross API calls
client.add_header('header', 'value')

# New
# These headers are NOT persisted accross API calls
client['Account'].getObject(headers={'header': 'value'})

Removing Additional Headers

# Old
client.remove_header('header')

# New
client['Account'].getObject()

Adding Additional HTTP Headers

# Old
client.add_raw_header('header', 'value')

# New
client['Account'].getObject(raw_headers={'header': 'value'})

Changing Authentication Credentials

# Old
client.set_authentication('username', 'api_key')

# New
client.username = 'username'
client.api_key = 'api_key'