Using Object Masks in the SoftLayer API
From SoftLayer Development Network Wiki
Most of the data types modeled in the SoftLayer API contain relational properties that tie one data type to another. For instance, a SoftLayer_Account has links to its domains, support tickets, hardware, users, and much more. By default, calling the SoftLayer_Account service's getObject method won't retrieve relational and count properties. In order to get them you would have to call the getUsers, getTickets, and other methods to retrieve this data. Making multiple API calls can significantly slow down an API-based application's response time, especially if it retrieves a lot of information at once. An alternative to making multiple method calls is to define an object mask in your method's header to retrieve all the information you need with a single call, adding a very noticeable increase in overall API responsiveness. Object masks are optional, but are the only way to retrieve a data type's count properties.
Structure
An object mask is an object of the type <service name>ObjectMask where <service name> is the name of the service you are accessing. The structure within an object mask is determined by the one making the API method call. No values are defined in an object mask, only the relational data you wish to retrieve. To retrieve a relational or count property, simply add an empty property to your request's object mask with the name of the properties you're trying to receive. For instance, If you wanted to retrieve your account's information along with all of it's open tickets, it's tickets' updates, the users the tickets are assigned to, the hardware attached to those tickets, the account's domains, all of the resource records within those domains, and finally the number of portal users associated with the account build the following structure:
- domains
- resourceRecords
- openTickets
- assignedUser
- attachedHardware
- updates
- userCount
Note that the first level of this object mask, the domains, openTickets, and userCount are all directly related to the SoftLayer_Account data type while the second level properties are related to the first level properties. Domains have resource records, and tickets have users, hardware, and updates. Create an object mask with this structure and send it in the header to a call to getObject in the SoftLayer_Account service to retrieve all of this data.
Creating an Object Mask
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 retrieving the structure above from the SoftLayer_Account service):
<SoftLayer_AccountObjectMask xsi:type="v3:SoftLayer_AccountObjectMask"> <mask xsi:type="slt:SoftLayer_Account" xmlns:slt="http://api.service.softlayer.com/soap/v3/SLTypes/"> <domains> <resourceRecords /> </domains> <openTickets> <assignedUser /> <attachedHardware /> <updates /> </openTickets> <userCount /> </mask> </SoftLayer_AccountObjectMask>
Again, note that we're not setting any values, just setting empty records for the data we want to retrieve. Since XML-RPC treats data as array keys and values, its structure is quite different:
<struct> <member> <name>SoftLayer_AccountObjectMask</name> <value> <struct> <member> <name>mask</name> <value> <struct> <member> <name>domains</name> <value> <struct> <member> <name>resourceRecords</name> <value> <array> <data/> </array> </value> </member> </struct> </value> </member> <member> <name>openTickets</name> <value> <struct> <member> <name>assignedUser</name> <value> <array> <data/> </array> </value> </member> <member> <name>attachedHardware</name> <value> <array> <data/> </array> </value> </member> <member> <name>updates</name> <value> <array> <data/> </array> </value> </member> </struct> </value> </member> <member> <name>userCount</name> <value> <array> <data/> </array> </value> </member> </struct> </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.
