SoftLayer Python Client

Common errors

• SoftLayer.exceptions.SoftLayerAPIError(500, 'Invalid API key or Username.')

  cause The provided SoftLayer username or API key is incorrect or expired.
  fix Verify your `SL_USERNAME` and `SL_API_KEY` environment variables or the credentials passed to `SoftLayer.Client()`. Ensure there are no leading/trailing spaces. API keys can be regenerated in the IBM Cloud portal.

• ImportError: cannot import name 'Client' from 'SoftLayer'

  cause Incorrect import statement. The `Client` class is an attribute of the `SoftLayer` module, not a direct export.
  fix Change your import statement from `from SoftLayer import Client` to `import SoftLayer` and then access the client using `SoftLayer.Client()`.

• SoftLayer.exceptions.SoftLayerAPIError(500, 'A SoftLayer_Exception_Public: No object mask for a SoftLayer_Virtual_Guest object was provided.')

  cause You are attempting to access properties of a SoftLayer object that were not retrieved because no object mask was specified in the initial API call.
  fix Add an `mask` parameter to your API call to explicitly request the desired properties. For example, `client['Virtual_Guest'].getObject(id=123, mask='mask[hostname, domain, primaryIpAddress]')`.

• SoftLayer.exceptions.SoftLayerAPIError(404, 'Unable to find object for identifier [ID].')

  cause The SoftLayer object with the specified ID does not exist or your account does not have permission to access it.
  fix Double-check the ID you are using. Verify that the object exists and that your API key has the necessary permissions to view or interact with it.

Warnings

• breaking CDN (Content Delivery Network) commands were removed from the `slcli` (SoftLayer CLI) and the underlying API methods were deprecated.
  Fix: Migrate any CDN-related automation to use the newer IBM Cloud CDN services or direct API calls if available. The legacy CDN service is no longer supported through this library.
• breaking The method for finding a VLAN's datacenter via `Vlan.primaryRouter` was migrated.
  Fix: If your code relies on `Vlan.primaryRouter` for datacenter information, review the official documentation or changelog for `softlayer-python` version 6.2.7 to understand the new recommended approach. Direct access to `primaryRouter` might lead to incorrect data or errors.
• gotcha SoftLayer API calls often return only partial data for objects by default. To retrieve full details (e.g., IP addresses, hardware components for a server), you must specify an 'object mask'.
  Fix: Always include an `mask` parameter in your API calls (e.g., `client['Virtual_Guest'].getObject(id=123, mask='mask[primaryIpAddress, backendIpAddress]')`). Refer to the SoftLayer API documentation for available properties for each service.
• gotcha When fetching large lists of objects (e.g., `getAllObjects`), the API often uses pagination. Incomplete results or unexpected behavior can occur if not handled correctly.
  Fix: Use the `iter_call` or `cf_call` methods provided by the library for iterating over large result sets, which handle pagination automatically. For manual pagination, use `limit` and `offset` parameters.
• gotcha Authentication can be configured via `~/.softlayer` config file, environment variables (`SL_USERNAME`, `SL_API_KEY`, `SL_ENDPOINT_URL`), or direct arguments to `SoftLayer.Client`.
  Fix: Understand the order of precedence: direct arguments > config file > environment variables. Ensure only one method is providing credentials to avoid conflicts or unexpected authentication failures. Using environment variables is often the most flexible for scripting.

Install

• pip install softlayer Install latest version

Imports

• Client
  wrong:

  from SoftLayer import Client

  correct:

  import SoftLayer
  client = SoftLayer.Client(...)

  The `SoftLayer` module is typically imported as a whole, and `Client` is accessed as `SoftLayer.Client`. Direct import `from SoftLayer import Client` might work in some contexts but is less common and can be ambiguous with other `Client` classes.
• SoftLayerAPIError

  from SoftLayer.exceptions import SoftLayerAPIError

Quickstart

This quickstart demonstrates how to initialize the SoftLayer client using environment variables for authentication and retrieve basic account information. It also shows an example of fetching virtual guests, highlighting the use of 'object masks' which are fundamental for getting detailed API responses.

import SoftLayer
import os

# SoftLayer API credentials can be set as environment variables (SL_USERNAME, SL_API_KEY)
# or passed directly. Environment variables are recommended for security.
# SL_ENDPOINT_URL is optional, defaults to 'api.softlayer.com/rest/v3.1'
client = SoftLayer.Client(
    username=os.environ.get('SL_USERNAME', 'YOUR_USERNAME'),
    api_key=os.environ.get('SL_API_KEY', 'YOUR_API_KEY'),
    endpoint_url=os.environ.get('SL_ENDPOINT_URL')
)

try:
    # Example: Get the account details
    account = client['Account'].getObject()
    print(f"Successfully connected to SoftLayer. Account ID: {account['id']}, Company: {account['companyName']}")

    # Example: List up to 5 virtual guests (VMs)
    # Object masks are crucial for retrieving full data
    mask = 'mask[id, hostname, domain, primaryIpAddress, primaryBackendIpAddress]'
    vms = client['Account'].getVirtualGuests(mask=mask, limit=5)
    if vms:
        print("\nVirtual Guests (first 5):")
        for vm in vms:
            print(f"- ID: {vm.get('id')}, Hostname: {vm.get('hostname')}, IP: {vm.get('primaryIpAddress')}")
    else:
        print("\nNo virtual guests found.")

except SoftLayer.exceptions.SoftLayerAPIError as e:
    print(f"Error connecting to SoftLayer API: {e}")
    print("Please ensure your SL_USERNAME and SL_API_KEY environment variables are correct.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")