The SoftLayer API

From SoftLayer Development Network Wiki

Jump to: navigation, search
SoftLayer Technologies Application Programming Interface is a development interface that gives developers and system administrators a direct interface into SoftLayer's backend systems. The functionality exposed by our API allows you to perform remote server management, monitoring, and retrieve information from SoftLayer's various systems such as accounting, inventory and DNS. The API powers all features in our customer portal. As we develop new features we in turn use them in our customer portal and they are available for use in the API.

Contents

Who Should Use the API?

The API is available to all SoftLayer customers. It can be used in new application development or be integrated into your existing product, providing your customers with unlimited control over their datacenter experience. The API can seamlessly and transparently be utilized to control all of your SoftLayer servers and services via SOAP or XML-RPC.

Using the SoftLayer API

Before You Begin

The SoftLayer API gives you a direct interaction with the objects that run our customer portal. Before developing for the API, it is incredibly beneficial to understand basic object-oriented programming concepts such as objects, properties, methods, and inheritance. Our API's methods are run against service objects in our backend systems which in turn return special data type objects in addition to standard data types like integers, booleans, and strings.

The API is a Remote Procedure Call (RPC) system. Each call involves sending data to an API endpoint and receiving structured data in return. The format used to send data between the API depends on which implementation of the API you choose to use. The API is available with SOAP or XML-RPC protocols, allowing integration with most modern programming languages. Before making API calls, it is also helpful to understand how SOAP or XML-RPC is implemented in your programming or scripting language. You can use either of the protocols in your application.

Creating an API User

Every call to the SoftLayer API is authenticated by a customer portal account. We highly recommend creating a user in our portal for running your API calls. Whether you are developing an application or using an API-based application developed by others you must authenticate within your program. Authentication to the API is based off of your portal user name and API key, a special authentication token reserved for API method calls.

Private Network Connectivity

The SoftLayer API endpoint server exists on the SoftLayer private network. Your API applications must have a connection to the private network in order to function. All of your servers purchased at SoftLayer have a direct connection to the private network. If you would like to run your API based application from outside of the SoftLayer private network, you will need to establish a connection to the private network via the SoftLayer VPN. Current VPN connection options include SSL VPN, PPTP, or IPSEC.

Basic API Usage

Services

As stated previously, our API is heavily based upon objects. Most calls to the API are made against an object in our backend systems. We refer to the objects you can make API calls against as services. Each SoftLayer API service defines an endpoint or WSDL (for SOAP users) that defines an object with methods to call upon those objects. Each of these services provides interaction with a specific function within SoftLayer's backend systems, but it's not uncommon for services to interact with each other. The API supports access to dozens of services, but the following are used most often:

Each service in the API follows a naming convention. All SoftLayer Services and data types begin with the text 'SoftLayer_' to differentiate SoftLayer API data in applications that rely on more than one API. Additionally, each service name defines the general function the service provides, "hardware", "account", "billing", "network" and so on. Each service and data type is extended from there with a name defining the service's specific function within that particular subsystem. We recommend starting out with the SoftLayer_Account service, which contains references to everything available to your SoftLayer customer account. From there, query the other services as needed using the data returned from the SoftLayer_Account service.

All of the SoftLayer API services along with their methods are described in detail in this wiki. See our list of API services and list of API methods for a more complete list of services and their methods to get started!

Data Types

Many of the API methods return standard data types such as integers, strings, and floating point numbers. Our API defines a number of extra data types that that encompass the wide range of method responses possible from an API call. These data structures can range in function from a Windows Update definition to a DNS A record to an invoice summary. These custom data types contain two types of properties. A data type's local properties directly reference the data type and are comprised of integers, strings, booleans, and other common data types. A data type's relational properties are themselves custom data types and show how custom data types relate to each other.

All of these data types are defined in this wiki. Check our list of API data types to see what kind of information retrieval is possible with the API.

Advanced API Usage

In addition to simple submit and retrieve RPC operations, our API allows developers to manage exactly how data is returned from each call through the use of special SOAP and XML-RPC headers.

Limiting Your Result Set

For more details on this topic, see Using Result Limits in the SoftLayer API.

Supported methods allow you to retrieve specific items from a list of items in a way similar to the SQL LIMIT option. Calls that return lists of data, such as SoftLayer_Account::getInvoices can return a number of items within the list starting from a certain position in the list. A method's individual page on this wiki will show if it can limit result data.

Using Object Masks

For more details on this topic, see Using Object Masks in the SoftLayer API.

While working with the API services and data types you should notice that data types frequently contain other data types as properties. The SoftLayer_User_Customer data type for instance contains the property account which contains the User's account information structured within the SoftLayer_Account data type. By default, to make API calls run much faster, a service's getObject method won't automatically retrieve these linked properties. If you want to retrieve one or more of the linked properties you can do by sending an object mask header along with your request. Like the result limit header, a method's page on this wiki will tell you if it can use an object mask or not.

See Also

External Links

Retrieved from "http://sldn.softlayer.com/wiki/index.php/The_SoftLayer_API"
Personal tools