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.Client(username="username", api_key="api_key")
>>> resp = client['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 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) and a timeout of 4 minutes.
client = SoftLayer.Client(
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 mask out 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 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="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 virtual server 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(username=None, api_key=None, endpoint_url=None, timeout=None, auth=None, config_file=None, proxy=None, user_agent=None)¶
A SoftLayer API client.
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
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:
>>> import SoftLayer >>> client = SoftLayer.Client() >>> client['Account'] <Service: Account>
- authenticate_with_password(username, password, security_question_id=None, security_question_answer=None)¶
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)¶
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:
>>> import SoftLayer >>> 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]¶
A SoftLayer Service.
Parameters: - client – A SoftLayer.API.Client instance
- str (name) – The service name
- __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
- 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.Client() >>> 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
- 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.Client() >>> 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:
>>> import SoftLayer >>> client = SoftLayer.Client() >>> gen = client['Account'].getVirtualGuests(iter=True) >>> for virtual_guest in gen: ... virtual_guest['id'] ... 1234 4321
SoftLayer.exceptions¶
Exceptions used throughout the library
license: | MIT, see LICENSE for more details. |
---|
- exception SoftLayer.exceptions.ApplicationError(fault_code, fault_string, *args)[source]¶
Application Error.
- exception SoftLayer.exceptions.InternalError(fault_code, fault_string, *args)[source]¶
Internal Server Error.
- exception SoftLayer.exceptions.InvalidCharacter(fault_code, fault_string, *args)[source]¶
There was an invalid character.
- exception SoftLayer.exceptions.InvalidMethodParameters(fault_code, fault_string, *args)[source]¶
Invalid method paramters.
- exception SoftLayer.exceptions.MethodNotFound(fault_code, fault_string, *args)[source]¶
Method name not found.
- exception SoftLayer.exceptions.NotWellFormed(fault_code, fault_string, *args)[source]¶
Request was not well formed.
- exception SoftLayer.exceptions.RemoteSystemError(fault_code, fault_string, *args)[source]¶
System Error.
- exception SoftLayer.exceptions.SoftLayerAPIError(fault_code, fault_string, *args)[source]¶
SoftLayerAPIError is an exception raised during API errors.
Provides faultCode and faultString properties.
- exception SoftLayer.exceptions.SpecViolation(fault_code, fault_string, *args)[source]¶
There was a spec violation.
Backwards Compatibility¶
As of 3.0, the old API methods and parameters no longer work. Below are examples of converting the old API to the new one.
Get the IP address for an account
# Old
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()
# New
import SoftLayer
client = SoftLayer.Client(username='username', api_key='api_key')
client['Account'].getObject(mask="ipAddresses", limit=10, offset=0)
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="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'