SoftLayer API Overview
SoftLayer's Application Programming Interface (API) is the development interface that gives developers and system administrators direct interaction with SoftLayer's backend system. The functionality exposed by our API allows users to perform remote server management, monitoring and retrieve information from SoftLayer's various systems such as accounting, inventory and DNS. Our API powers many of the features in the SoftLayer Customer Portal, which typically means if an interaction is possible in the Customer Portal, it may be executed in our API, as well.
Who Should Use the API?
The SoftLayer API (SLAPI) is available to all SoftLayer customers at no additional charge. We encourage our customers with a basic knowledge of object-oriented programming to take full advantage of the capabilities the SLAPI offers. While SoftLayer customers use the SLAPI for a variety of tasks, the ability to programmatically interact with all portions of the SoftLayer environment within the API results in the majority of our customers using the SLAPI to automate tasks.
Using the SoftLayer API
Before you Begin
The SLAPI gives users direct interaction with the objects that run the Customer Portal. Before developing for the SLAPI, it is incredibly beneficial to understand basic object-oriented programming concepts such as objects, properties, methods and inheritance. The SLAPI's methods are run agains service objects in our backend systems, which return both SoftLayer-specific data type objects and standard data types like integers, booleans and strings.
The SLAPI is a Remote Procedure Call system. Each call involves sending data towards an API endpoint and receiving structured data in return. The format used to send and receive data with the SLAPI depends on which implementation of the API you choose. The SLAPI currently uses SOAP, XML-RPC or REST for data transmission. Before making API callas, it's helpful to understand how to use these protocols in your programming or scripting language. You can use any of the implementation in your application. We have also provided a number of service-specific API clients available in a variety of our supported languages on our github profile.
Creating an API User
Every call to the SLAPI is authenticated by a Customer Portal account. Accounts on the Customer Portal can contain multiple users and we highly recommend creating a unique Customer Portal user for running API calls. Whether you're developing an application or using an API-based application developed by others, you must authenticate within your program to access information about and interact with any aspect of your account. Authentication to the SLAPI requires your Customer Portal user name and API key, a special authentication token reserved for API method calls. User permissions defined in the Customer Portal are reflected in the API calls.
Choosing the Public or Private Network
SLAPI endpoint servers exist on SoftLayer's public and private networks. Your API-based applications may connect from any host on the Internet; however, SoftLayer's private network offers an extra layer of data security. Additionally, SoftLayer offers a variety of private network API endpoints, which are only accessible when connected to the private network. All servers and computing instances associated with a SoftLayer account have a direct connection to the private network and do not require additional authentication. If you wish to use private endpoints from another device, a VPN connection into our private network is required.
Basic API Concepts
A service is an endpoint associated with internal SoftLayer systems. Each service is a collection of methods, or actions, which can be performed. A list of all SLAPI services can be found in the Reference section of this site.
Upon accessing the Services section for the desired API, a list of all available services is displayed on the left side of the screen. All SoftLayer services begin with "SoftLayer_" and contain additional terms that define the general function the service provides: "Hardware", "Account", "Billing", "Network", etc. Each service is extended from there with a name that defines the service's specific function within that particular subset. Each service associated with the SoftLayer API has a unique name. While some services, such as SoftLayer_Account and SoftLayer_Account_Address, may share a common prefix, their interaction is not necessarily similar and there is no direct inheritance for services of a similar name. Because of this, each service should be approached individually.
To view details for a specific service, click the service name. Each service's page includes a list of methods available for that service and many also include a brief overview to explain the service. While each service offices a unique set of methods, many services offer the getObject method. These methods can be used to retrieve an object of the same type from the API. For example, calling the getObject method on the SoftLayer_Network_Subnet service will return a SoftLayer_Network_Subnet data type object.
A method is a specific action that can be performed for a SLAPI service. Each method returns a scalar or structured data type and may require specific parameters, permissions or headers to run. Method parameters should be passed using the techniques described in each language's or endpoint's documentation. In situations where multiple parameters are required, pass the parameters in the order they appear on the Method page from top to bottom. The screenshot below displays the required parameters for the SoftLayer_Monitoring_Agent::getGraph method. When running this method, pass the parameters in the following order: configurationValues, beginDate, endDate.
A full list of parameters, permissions and headers is available on each Method page.
A data type is a structured that contains a collection of scalar values and other data types. In addition to traditional scalar values such a string, bool or int, the SLAPI also uses complex data types containing properties that define the objects passed to and returned by methods in the SLAPI. Each data type potentially contains a number of local, relational, and count properties.
A local property is a direct child of a data type. Local properties are typically returned when getObject() is called. Some, if not all, local properties are required when creating an instance of this data type when calling createObject().
A relational property is an indirect child of a data type. Relational properties are defined in other data types or their properties. For example, the SoftLayer_Account data type has a relational property for hardware. This relational property is an array of SoftLayer_Hardware data types. When tapped with an object mask, this property will return an array that contains a SoftLayer_Hardware object for each hardware device on the account.
A count property is a convenience property that can be used to determine the total number of objects associated with a property. For example, we could retrieve the total number of VLANs associated with a specific server by using an object mask with included Softlayer_Hardware_Server->networkVlanCount.
Advanced API Concepts
In addition to the typical create, read, update and delete actions, the SLAPI allows developers to define how data is returned from each call through the use of special API call headers. These headers allow an additional level on control over the amount of data returned by the API.
A result limit is a support method that allows you to define an offset and amount of objects to return. This allows for pagination of large data sets.
An object mask allows the user to specify which local properties to return from a method and retrieve information found in both relational and count properties. A map, or ìmaskî is created to define the specific data to include in the return value. For example, it is possible to gather the IDs for each VLAN on a SoftLayer_Hardware_Server by specifying an object mask for ìnetworkVlans.idî when calling SoftLayer_Hardware_Server::getObject.
Part of the art of mastering the SLAPI is navigating through object masks to achieve the desired results. More often than not, there is more than one way to get to a specific data point and some can be more efficient than others.
Where to go From Here
Now that you know the basics, it is time to start coding. Check out our Getting Started Guide to see how to create an API user and make your first call. We also maintain a number of guides for specific languages:
Other useful links: