Articles > SoftLayer API Overview

SoftLayer API Overview

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 many of the features in our customer portal. As we code new API features we in turn use them in our customer portal.

Who Should Use the API?

The API is open for use by all SoftLayer customers. If you have a head for software development then please make full use of this wiki. It's here for you to make the best use of the SoftLayer API in your applications and scripts.

Using the SoftLayer API

Before You Begin

The SoftLayer API gives you a direct interaction with the objects that run our cusomer portal. Before developing for the API it's 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 system. Each call involves sending data towards an API endpoint and receiving structured data in return. The format used to send data back and forth with the API depends on which implementation of the API you choose to use. Our API uses SOAP, XML-RPC, and REST for data transmission. Before making API calls it's also helpful to understand how to use these protocols in your programming or scripting language. You can use any of the implementations in your application.

Creating an API User

Every call to the SoftLayer API is authenticated by a portal customer account. We highly recommend creating a user in our portal for running your API calls. Whether you're 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 your portal user name and API key, a special authentication token reserved for API method calls.

Choosing the Public or Private Network

The SoftLayer API endpoint servers exist on both the SoftLayer 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. You must have a connection to the private network in order to use our private network API endpoints. All of your servers and computing instances purchased at SoftLayer have a direct connection to the private network. Otherwise you must establish a VPN connection into our private network to use our private endpoints.

Basic API Usage

Services

As we stated before 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 provide interaction with a specific function within SoftLayer's backend systems, but it's not uncommon for services to interact with each other. Currently the API provides the following services:

As you can see 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. From there 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 that defines 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.

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 complex 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 three 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. Data type count properties store unsigned integer values defining the number of relational properties associated with an account. For example, the domains relational property on the SoftLayer_Account data type refers to the DNS zones associated with that count, while domainCount stores the number of domains that account has.

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 API call headers.

Limiting Your Result Set

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 like this.

Using Object Masks

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.

Where To Go From Here

Now that you know the basics it's time to start coding. Check out our Getting Started Guide to see how to make your first API user and call. We also maintain a number of language specific pages to help you integrate the API with your favorite programming language. After that there a few places you can turn for help and guidance:

  • The SLDN Forums: Share your ideas and implementation directly with other SoftLayer API users and SoftLayer employees.
  • SoftLayer's github profile: SoftLayer maintains a number of open projects on the github social code hosting site. Please follow us, check out our public repositories, and fork our projects. We don't mind at all.
  • Public code snippets: SoftLayer publishes a number of code snippets covering various common API usage topics. Look here to see how it's done. Please contact us if you'd like to see something new covered in your preferred language.

See Also

Was this helpful?
© 2012 SoftLayer Technologies, Inc. All rights reserved.