Object Masks

Overview

In order to obtain relational data from an object in the API you must declare an object mask in your API call. With standard object masks, relational data is pulled using a SOAP header, an XML-RPC struct or a GET parameter in REST. Extended object masks make use of a Domain-specific language to reduce the effort required to express what data should be returned from the API. In order to support this new method of object mask, a new input method has been added to each protocol.

Structure

Root Node

Extended object masks start from a "root node" which is a property set or a string of "mask" which acts as an alias for the object retuned by the API call. For example, when calling SoftLayer_Hardware::getObject the root node "mask" will represent a SoftLayer_Hardware Object.

So if we were to send "mask" as our object mask for SoftLayer_Hardware::getObject, the entire SoftLayer_Hardware object would be returned as if no mask was included.

Property

A property can be the name of any local or relational property of the returned object type and is appended to the mask with a peroid: ".".

mask.networkComponents

The above object mask used when calling SoftLayer_Hardware::getObject will return the SoftLayer_Hardware object, in addition to an array "networkComponents" containing the SoftLayer_Network_Components associated with that hardware.

It is possible to chain together multiple properties in order to drill down and receive even relational properties of relational properties. For example, if we wanted to receive a list of network components related to a specific hardware device, a list of VLANs related to those network components and even the primary subnet of each of those VLANs we could use an object mask:

mask.networkComponents.networkVlans.primarySubnet

Multiple properties may be defined by listing in the object mask separated by a comma.

mask.networkComponents,mask.primaryIpAddress,mask.billingItem

Property Set

Property sets can be used as an alternative to listing out each property from its root node. A property set is used to declare a list of properties to obtain from an object and is helpful for reducing the verbosity of an object mask.

A property set is a comma-separated list of properties enclosed in brackets [ ] which follows a property name.

The following masks can be considered equivalent:

[mask.id,mask.fullyQualifiedDomainName,mask.networkComponents.networkHardware,mask.networkComponents.uplinkComponent]
mask 
[
    id,fullyQualifiedDomainName,networkComponents [
        networkHardware,uplinkComponent
    ]
]

Payload reduction

Any local properties defined in a mask will result in the API returning only the specified local properties of the object. This feature allows for reduction of the API return data size and can help avoid the need for pagination or additional complication.

For example, when invoking SoftLayer_Hardware::getObject the following mask may be used to retrieve only the id, fullyQualifiedDomainName, and primaryIpAddress from the SoftLayer_Hardware record. In addition, it will return only the longName from the datacenter, and the id, name, and port of each networkComponent.

mask[id,fullyQualifiedDomainName,primaryIpAddress,datacenter.longName,networkComponents[id,name,port]]

Type

By default the type of returned objects will be inferred and is not required. However it is possible to declare a type for a specific property.

A type is defined by placing a parenthesis set after the property name with the type name enclosed. A type will need to be defined when the default property type does not have a particular property that you need.

For example, the controlPanel property is not defined on SoftLayer_Hardware and as such you will get an error if requesting it via mask.controlPanel on a call to SoftLayer_Account::getHardware. In order to request the value you must declare the root property to be of a particular type. An example is below.

mask(SoftLayer_Hardware_Server).controlPanel

If necessary, a property may be defined multiple times on the same level with different types.

The mask below is an example for invoking SoftLayer_Search::search with two expected data types to be returned:

mask
[
    resource(SoftLayer_Hardware)
    [
        id,
        fullyQualifiedDomainName,
        datacenter.longName,
        networkComponents.primaryIpAddress
    ],
    resource(SoftLayer_Virtual_Guest)
    [
        id,
        fullyQualifiedDomainName,
        datacenter.longName,
        networkComponents.primaryIpAddress
    ]
]

Syntax

NOT FOUND: syntax.png

API interaction

SOAP

To send the object mask to the SOAP API you will need to provide a SoftLayer_ObjectMask header with the string object mask for the value in the mask property of the header.

XML-RPC

The same SoftLayer_ObjectMask header may be provided in the XML-RPC headers section of the request.

REST

The REST interface will accept the object mask via the objectMask GET parameter.

Our SLAPI bindings found in our github projects have been updated to support this new form of string object mask.

Legacy Object Masks

Please see Legacy-Object-Masks for usage information on the legacy object mask syntax