Getting Started

From SoftLayer Development Network Wiki

Jump to: navigation, search

If one thing can be said for the SoftLayer API, it's certainly large. SoftLayer's API encompasses every possible thing you can do with your account and services. At over 1,000 methods in over 75 services it's easy to get a little lost. We hope this guide can get you started on the right path.

Contents

Before You Start

Choosing a Protocol

SoftLayer's API can be accessed by SOAP, XML-RPC, or RESTful means. Choose the best protocol for your preferred language and situation. We generally recommend using our SOAP interface, as it's the most comprehensive and most easily models the API's services and data types.

SOAP XML-RPC REST
Advantages It's the fastest of the three protocols and allows you to make direct calls against SoftLayer's API services and data types. Wide support amongst programming languages. Most programming languages support standard HTTP protocol operations if they don't have explicit support for SOAP or XML-RPC.
Disadvantages Initial WSDL consumption may take some time. Lack of complex type specifications may require extra work when working with specific data types. REST URLs can become complex, especially when working with complex data structures.
Recommended For Calling SoftLayer API services as code local to your project. Making API calls in languages without proper SOAP support. Quickly calling get*() methods and retrieving data with a minimum amount of hierarchy.
Recommended Languages C#, Perl, PHP, Visual Basic .NET PHP, Python Ruby, Any language that supports standard HTTP protocol operations, JSON parsing, and XML parsing

Getting Your API Key

API calls are authenticated by the username you use to authenticate to the SoftLayer portal and a special API key. Log into the SoftLayer customer portal, then head to the Administrative then User Admin menus. From there go to the API Access page to generate your key. Use these keys to authenticate your calls. You'll have the most access by using your account's master user to make API calls, but your code may be more secure if you use a sub-account with a more limited permission set.

Using The Private Network

SoftLayer has API endpoints listening on the private network. Private network calls can only be made from systems on the private network, either from servers or computing instances purchased from SoftLayer or from systems VPN'd into the private network. On the other hand private network calls aren't made over the public Internet. They're more secure and take less time to execute.

To use the private network in your API call replace https://api.softlayer.com with http://api.service.softlayer.com. Continue using https if you're using our REST API though.

Your First API Call

The getObject() method in the SoftLayer_Account service is a simple call that only requires an authentication header. It returns basic, top-level information about your SoftLayer account and is a great way to test your first API call. Here are a few ways to get it going:

Raw SOAP

Have you read our SOAP guide? 

 
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://api.softlayer.com/soap/v3/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Header>
        <ns1:authenticate>
            <username>set me</username>
            <apiKey>set me too</apiKey>
        </ns1:authenticate>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <ns1:getObject/>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
 

Raw XML-RPC

Have you read our XML-RPC guide? 

 
<?xml version="1.0" encoding="iso-8859-1"?>
<methodCall>
    <methodName>getObject</methodName>
    <params>
        <param>
            <value>
                <struct>
                    <member>
                        <name>headers</name>
                        <value>
                            <struct>
                                <member>
                                    <name>authenticate</name>
                                    <value>
                                        <struct>
                                            <member>
                                                <name>username</name>
                                                <value>
                                                    <string>set me</string>
                                                </value>
                                            </member>
                                            <member>
                                                <name>apiKey</name>
                                                <value>
                                                    <string>set me too</string>
                                                </value>
                                            </member>
                                        </struct>
                                    </value>
                                </member>
                            </struct>
                        </value>
                    </member>
                </struct>
            </value>
        </param>
    </params>
</methodCall>
 

REST URL

Have you read our REST guide? 
https://<username>:<apiKey>@api.service.softlayer.com/rest/v3/SoftLayer_Account

C#

Have you read our C# guide? 

 
String username = "set me";
String apiKey = "set me";
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
SoftLayer_AccountService accountService = new SoftLayer_AccountService();
accountService.authenticateValue = authenticate;
 
SoftLayer_Account account = accountService.getObject();
 

Perl

Have you read our Perl guide? 

 
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'set me';
 
my $account = SoftLayer::API::SOAP->new('SoftLayer_Account', undef, $api_username, $api_key)->getObject();
 

PHP

Have you read our PHP guide? 

 
<?php
 
require_once('/path/to/SoftLayer/SoapClient.class.php');
 
$apiUsername = 'set me';
$apiKey = 'set me';
 
$client = SoftLayer_SoapClient::getClient('SoftLayer_Account', null, $apiUsername, $apiKey);
$account = $client->getObject();
 

Python

Have you read our Python guide? 
 
import SoftLayer.API
 
api_username = 'set me'
api_key = 'set me'
 
client = SoftLayer.API.Client('SoftLayer_Account', None, api_username, api_key)
account = client.getObject()
 

Visual Basic .NET

Have you read our Visual Basic .NET guide? 

 
Dim username As String = "set me"
Dim apiKey As String = "set me"
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()
accountService.authenticateValue = authenticate
 
Dim account as SoftLayer_Account = accountService.getObject()
 

Where To Go From Here

The SoftLayer_Account service is an umbrella service. Everything relates back to your account record, your inventory, accounting records, domains, support tickets, and everything else. Where you go from here depends solely on what you're trying to accomplish. Make a few more queries to the SoftLayer_Account service to see what data types are returned. Try out a few object masks to see how our data types relate to each other. If you need to work with another service then head to its manual page to see what you can do with it. Here are a few of the more common services used:


The SoftLayer API
Main Page • The SoftLayer API • Getting Started
Retrieved from "http://sldn.softlayer.com/wiki/index.php/Getting_Started"
Personal tools