{"id":10242,"library":"softlayer","title":"SoftLayer Python Client","description":"The `softlayer-python` library provides both a Python API client and a command-line interface (CLI) for interacting with the IBM Cloud SoftLayer API. It abstracts the complexities of the SOAP/REST API, allowing developers to manage SoftLayer resources such as virtual servers, bare metal, storage, and networking. The current version is 6.2.9, and the project maintains an active release cadence with frequent minor updates and bug fixes.","status":"active","version":"6.2.9","language":"en","source_language":"en","source_url":"https://github.com/SoftLayer/softlayer-python","tags":["softlayer","ibm cloud","api client","infrastructure","cloud management"],"install":[{"cmd":"pip install softlayer","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for making HTTP requests to the SoftLayer API.","package":"requests","optional":false}],"imports":[{"note":"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.","wrong":"from SoftLayer import Client","symbol":"Client","correct":"import SoftLayer\nclient = SoftLayer.Client(...)"},{"symbol":"SoftLayerAPIError","correct":"from SoftLayer.exceptions import SoftLayerAPIError"}],"quickstart":{"code":"import SoftLayer\nimport os\n\n# SoftLayer API credentials can be set as environment variables (SL_USERNAME, SL_API_KEY)\n# or passed directly. Environment variables are recommended for security.\n# SL_ENDPOINT_URL is optional, defaults to 'api.softlayer.com/rest/v3.1'\nclient = SoftLayer.Client(\n    username=os.environ.get('SL_USERNAME', 'YOUR_USERNAME'),\n    api_key=os.environ.get('SL_API_KEY', 'YOUR_API_KEY'),\n    endpoint_url=os.environ.get('SL_ENDPOINT_URL')\n)\n\ntry:\n    # Example: Get the account details\n    account = client['Account'].getObject()\n    print(f\"Successfully connected to SoftLayer. Account ID: {account['id']}, Company: {account['companyName']}\")\n\n    # Example: List up to 5 virtual guests (VMs)\n    # Object masks are crucial for retrieving full data\n    mask = 'mask[id, hostname, domain, primaryIpAddress, primaryBackendIpAddress]'\n    vms = client['Account'].getVirtualGuests(mask=mask, limit=5)\n    if vms:\n        print(\"\\nVirtual Guests (first 5):\")\n        for vm in vms:\n            print(f\"- ID: {vm.get('id')}, Hostname: {vm.get('hostname')}, IP: {vm.get('primaryIpAddress')}\")\n    else:\n        print(\"\\nNo virtual guests found.\")\n\nexcept SoftLayer.exceptions.SoftLayerAPIError as e:\n    print(f\"Error connecting to SoftLayer API: {e}\")\n    print(\"Please ensure your SL_USERNAME and SL_API_KEY environment variables are correct.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"CDN (Content Delivery Network) commands were removed from the `slcli` (SoftLayer CLI) and the underlying API methods were deprecated.","severity":"breaking","affected_versions":">=6.2.7"},{"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.","message":"The method for finding a VLAN's datacenter via `Vlan.primaryRouter` was migrated.","severity":"breaking","affected_versions":">=6.2.7"},{"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.","message":"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'.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, partially addressed in 6.2.9 for `cf_call`"},{"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.","message":"Authentication can be configured via `~/.softlayer` config file, environment variables (`SL_USERNAME`, `SL_API_KEY`, `SL_ENDPOINT_URL`), or direct arguments to `SoftLayer.Client`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","cause":"The provided SoftLayer username or API key is incorrect or expired.","error":"SoftLayer.exceptions.SoftLayerAPIError(500, 'Invalid API key or Username.')"},{"fix":"Change your import statement from `from SoftLayer import Client` to `import SoftLayer` and then access the client using `SoftLayer.Client()`.","cause":"Incorrect import statement. The `Client` class is an attribute of the `SoftLayer` module, not a direct export.","error":"ImportError: cannot import name 'Client' from 'SoftLayer'"},{"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]')`.","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.","error":"SoftLayer.exceptions.SoftLayerAPIError(500, 'A SoftLayer_Exception_Public: No object mask for a SoftLayer_Virtual_Guest object was provided.')"},{"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.","cause":"The SoftLayer object with the specified ID does not exist or your account does not have permission to access it.","error":"SoftLayer.exceptions.SoftLayerAPIError(404, 'Unable to find object for identifier [ID].')"}]}