SOAP

AT&T Cloud Architect provides a SOAP interface in addition to XML-RPC and REST. We recommend using the SOAP API, as it is the most comprehensive API we currently offer.

WSDL URLs and Files

The AT&T Cloud Architect 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:

https://api.attcloudarchitect.com/soap/v3/<serviceName>?wsdl

or

http://api.service.attcloudarchitect.com/soap/v3/<serviceName>?wsdl

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 AT&T Cloud Architect's private network. It's a faster, more secure way to communicate with AT&T Cloud Architect, but the system making API calls must be on AT&T Cloud Architect's private network. All AT&T Cloud Architect servers come with access to our private network, including cloud computing instances. 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 AT&T Cloud Architect API. Once a WSDL is imported by your consuming service, every data type and API service method should be available in your project.

Sending API Call Headers

Important API headers, such as authentication, initialization parameters, and object masks are sent to the AT&T Cloud Architect API as SOAP headers. Each call header has an associated complex type. This sample header contains authentication information and an initialization parameter for the Hardware_Server API service.

<SOAP-ENV:Header>
    <ns1:authenticate>
        <username>set me</username>
        <apiKey>set me too</apiKey>
    </ns1:authenticate>
    <ns1:Hardware_ServerInitParameters>
        <id>1234</id>
    </ns1:Hardware_ServerInitParameters>
</SOAP-ENV:Header>

Using Object Masks

Add an object mask to your API call by adding an object mask complex type, which corresponds to the API service you're 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 Account API service has the name AccountObjectMask and the Hardware_Server service's corresponding object mask class name is Hardware_ServerObjectMask.

Declare a <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:

  • The account's physical hardware records
  • That hardware's operating system record
  • Operating system passwords
  • Network components
  • Datacenter in which the hardware is located
  • Number of processors in each hardware
<Hardware_ServerObjectMask xsi:type="v3:Hardware_ServerObjectMask">
    <mask xsi:type="slt:Hardware_Server" xmlns:slt="https://api.attcloudarchitect.com/soap/v3/SLTypes/">
        <operatingSystem>
            <passwords />
        </operatingSystem>
        <datacenter />
        <processorCount />
    </mask>
</Hardware_ServerObjectMask>

Using Result Limits

Place a result limit in your API call by adding a resultLimit complex type to your call headers. The resultLimit object has two properties:

  • "limit", an integer representing the number of results to limit your call
  • "offset", an integer offset to begin your result set

This resultLimit header represents a result with a limit of 2, starting at offset 0.

<resultLimit xsi:type="slt:resultLimit" xmlns:slt="http://api.service.attcloudarchitect.com/soap/v3/SLTypes/">
    <limit xsi:type="xsd:int">2</limit>
    <offset xsi:type="xsd:int">0</offset>
</resultLimit>

Error Handling

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.

Caveats

WSDL and XSD File Sizes

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 AT&T Cloud Architect 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.

Referenced API Components

Services

Data Types

Methods