SOAP

Simple Object Access Protocol (SOAP) is an XML-based protocol for the exchange of information between applications over HTTP. Visit the SOAP Messaging Framework Web site for information about SOAP-based implementations. Most Adobe Online Marketing Suite APIs support a SOAP interface, which allows you to use any SOAP development toolkit to interface with Online Marketing Suite Web services. To use the SOAP interface to access the Web Services APIs, you should understand the following :

  • Simple Object Access Protocol (SOAP)
  • XML, specifically as it relates to SOAP
  • Web Services Description Language (WSDL)
  • XML Schema Definition Language (XSD)

Online Marketing Suite Web services use an RPC-style version of SOAP. Your program sends a SOAP request; Online Marketing Suite servers process the request and return a response. Both the request and the response are sent as XML messages with a header and a body.

To learn more about SOAP, see the SOAP Tutorial at W3Schools, or the SOAP Wikipedia entry.

SOAP Development Toolkits

The easiest way to use Online Marketing Suite APIs is with a toolkit that will interpret WSDL files and provide a framework for easier development. Development toolkits will encode and decode XML request/response messages for you. More specifically, toolkits allow you to work in an object oriented environment, so you can both create and receive objects that are translated to and from XML by the toolkit.

You should choose your toolkit to match the language you are using. The toolkits vary in performance, capability and user-friendliness. While a few will take care of the XML coding for you, others require you to write some XML yourself. Commonly used toolkits include:

By using a SOAP toolkit that handles the XML generation, you should rarely have to write XML code to use Online Marketing Suite Web services. However, some toolkits might require you to hand-code some of the XML yourself. For example, nusoap.php requires you to write the XML namespace for input parameters.

NOTE: Online Marketing Suite Web services support rpc/enc style SOAP, not document/literal style. Some toolkits work differently for rpc/enc style Web services than for document/literal style SOAP.

Using SOAP

The Online Marketing Suite processes Web services requests as defined in the XML-based Web Services Definition Language file (see Downloading the WSDL). The WSDL describes each method that the Web service can perform, including supported parameters and the response structure. See the Web Services Documentation for detailed information about each Web Services method.

Web Services requests are sent via secure sockets layer (SSL) HTTPS requests. The SOAP request (in XML format) is sent as an HTTP POST with a special SOAPAction header. The SOAP response is returned as a response to the POST request. All of these calls are encrypted with SSL, thereby protecting your data privacy.

The SOAP header contains Important metadata about your message, including Web Services Authentication information. The SOAP body contains the actual method call, including all required parameters.

Sample SOAP Request

      <?xml version="1.0" encoding="UTF-8"?>
      <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.omniture.com/" 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>
          <wsse:Security xmlns:wsse="http://www.omniture.com" wsse:mustUnderstand="1">
            <wsse:UsernameToken wsse:Id="User">
              <wsse:Username>jdoe:corp1</wsse:Username>
              <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">6NBUW/HtNH+XguDVHAlcKx8wESc=</wsse:Password>
              <wsse:Nonce>M2UxZmFmNjViMjZhNWE1MWRiMDBhMzcx</wsse:Nonce>
              <wsse:Created>2010-04-23T14:17:14Z</wsse:Created>
            </wsse:UsernameToken>
          </wsse:Security>
        </SOAP-ENV:Header>
        <SOAP-ENV:Body>
          <ns1:Company.GetTokenUsage/>
        </SOAP-ENV:Body>
      </SOAP-ENV:Envelope>

Sample SOAP Response

      <?xml version="1.0" encoding="UTF-8"?>
      <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="http://www.omniture.com/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <SOAP-ENV:Body>
          <ns1:Company.GetTokenUsageResponse xmlns:ns1="http://www.omniture.com/">
            <return xsi:type="tns:token_usage_container">
              <allowed_tokens xsi:type="xsd:int">2000</allowed_tokens>
              <used_tokens_total xsi:type="xsd:int">1</used_tokens_total>
              <token_period xsi:type="xsd:string">month</token_period>
              <status xsi:type="xsd:string">normal</status>
              <overage_enabled xsi:type="xsd:int">0</overage_enabled>
              <token_usage xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="tns:user_token_usage[2]">
                <item xsi:type="tns:user_token_usage">
                  <login xsi:type="xsd:string">atate</login>
                  <name xsi:type="xsd:string">John Doe</name>
                  <used_tokens xsi:type="xsd:int">0</used_tokens>
                </item>
                <item xsi:type="tns:user_token_usage">
                  <login xsi:type="xsd:string">jdoe</login>
                  <name xsi:type="xsd:string">John Doe</name>
                  <used_tokens xsi:type="xsd:int">1</used_tokens>
                </item>
              </token_usage>
            </return>
          </ns1:Company.GetTokenUsageResponse>
        </SOAP-ENV:Body>
      </SOAP-ENV:Envelope>