The SoftLayer SOAP API has one endpoint per available API service. Each endpoint has a unique URL containing the service name of the API service that it calls. For example:
In these examples,
"<serviceName>" would be replaced with the name of the API services you wish to call. Use the second URL to access the SOAP API over SoftLayer’s private network. It’s a faster, more secure way to communicate with SoftLayer, but the system making API calls must be on SoftLayer’s private network. All SoftLayer servers come with access to our private network, including CCIs. Additional private IP addresses are available for purchase should they be needed.
Each WSDL defines that specific service’s available methods and includes an XSD file that defines every complex type available to the SoftLayer API. Once a WSDL is imported by your consuming service, every data type and API service method should be available in your project.
The SoftLayer_Account/getObject|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:
<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>
Important API headers, such as authentication, initialization parameters, and object masks are sent to the SoftLayer API as SOAP headers. Each call header has an associated complex type. This sample header contains authentication information and an initialization parameter for the SoftLayer_Hardware_Server API service.
<SOAP-ENV:Header> <ns1:authenticate> <username>set me</username> <apiKey>set me too</apiKey> </ns1:authenticate> <ns1:SoftLayer_Hardware_ServerInitParameters> <id>1234</id> </ns1:SoftLayer_Hardware_ServerInitParameters> </SOAP-ENV:Header>
Add an object mask to your API call by adding an object mask complex type which corresponds to the API service you are calling. Object masks are named according to your API service with a
"<serviceName>ObjectMask" format, where
<serviceName> corresponds to the name of the API service you’re calling. For instance, an object mask for the SoftLayer_Account API service has the name
SoftLayer_AccountObjectMask and the SoftLayer_Hardware_Server service’s corresponding object mask class name is
<mask> inside your object with the name “mask” of the type defined by your API service containing the relational and count properties you wish to retrieve along with your API call result. Each item in your object mask is an empty XML value.
This example retrieves the following information:
<SoftLayer_Hardware_ServerObjectMask xsi:type="v3:SoftLayer_Hardware_ServerObjectMask"> <mask xsi:type="slt:SoftLayer_Hardware_Server" xmlns:slt="https://api.softlayer.com/soap/v3/SLTypes/"> <operatingSystem> <passwords /> </operatingSystem> <datacenter /> <processorCount /> </mask> </SoftLayer_Hardware_ServerObjectMask>
Place a result limit in your API call by adding a
resultLimit complex type to your call headers. The resultLimit object has two properties:
<resultLimit xsi:type="slt:resultLimit" xmlns:slt="http://api.service.softlayer.com/soap/v3/SLTypes/"> <limit xsi:type="xsd:int">2</limit> <offset xsi:type="xsd:int">0</offset> </resultLimit>
The SOAP API returns SOAP faults if your call encounters an error. The fault’s
faultcode corresponds to the type of exception thrown by your error, while the fault’s
faultstring contains your error message.
Depending on the API service you request, your WSDL consuming service may download over a megabyte of information when it downloads a WSDL file. The WSDL’s included XSD defines every data type available at SoftLayer and is rather large. Your first API call may take some time while the WSDL is downloaded and processed. We highly recommend local WSDL and XSD caching so repeated calls don’t take as long.