Using Initialization Parameters in the SoftLayer API

From SoftLayer Development Network Wiki

The objects represented in the SoftLayer API have to be instantiated before any methods can be called on them. SoftLayer provides a way to instantiate your data objects by passing the service's initialization parameter in the header of your API calls. Nearly all data represented in the SoftLayer API is identified by a unique integer value. For instance, your SoftLayer customer account number is one of these unique identifiers and consequently is the value of the initialization parameter in your calls to the SoftLayer_Account service.

Contents 1 Structure 2 Creating an Initialization Parameter 3 Exceptions to the Rule 4 See Also

Structure

An initialization parameter is an object of the type <service name>InitParameters where <service name> is the name of the service you're accessing. Each initialization parameter has a single integer property called id, representing the unique identifier of the object you're trying to retrieve or edit. For instance, The SoftLayer_Network_Backbone service's initialization parameter is stored in the SoftLayer_Network_BackboneInitParameters data type with the single integer property id.

Creating an Initialization Parameter

Languages that support SOAP usually have built-in mechanisms to add headers to a SOAP call (the SoapHeader PHP class, for instance). If building manual SOAP calls, then format your request XML akin to the following (assuming you're working with the SoftLayer_Network_Backbone service):

 
<SoftLayer_Network_BackboneInitParameters xsi:type="v3:SoftLayer_Network_BackboneInitParameters">
    <id xsi:type="xsd:int">115</id>
</SoftLayer_Network_BackboneInitParameters>
 

Replace the value of the id field with the unique identifier of the backbone you're querying. Since XML-RPC treats data as array keys and values, it's initialization parameter structure is quite different:

 
<struct>
  <member>
    <name>SoftLayer_Network_BackboneInitParameters</name>
    <value>
      <struct>
        <member>
          <name>id</name>
          <value>
            <int>123</int>
          </value>
        </member>
      </struct>
    </value>
  </member>
</struct>
 

Again, most programming and scripting languages with SOAP and XML-RPC support have built-in methods to create request headers, but if formatting a call manually then place XML like the values above into the headers of your requests.

Exceptions to the Rule

Some methods do not require initialization parameters if they're not necessary. These kinds of methods usually create objects or retrieve groups of objects. For instance, the SoftLayer_Ticket addUpdate method requires an initialization parameter set since it relates to updating a specific ticket, but the createStandardAdministrationTicket method does not since there is no existing ticket to reference. If a method does not require an initialization parameter, then its service's initialization parameter data type is absent from its manual page.

See Also

• API methods that require initialization parameters
• API methods that do not require initialization parameters