Requests and Responses

A SOAP conversation consists of a request and a response, for instance:

"I'd like to schedule a campaign, with email X to contact list Y, on dd/mm/yyyy at 14:00 GMT"

The request is being made to a method, an action, with the parameters that specify what the method should do.

The response is likely to be either:

"Success, I've scheduled this campaign for you."

or
"Error, I couldn't schedule this because xyz"

Where XYZ is either a validation issue, issue with the parameters, or the request was malformed in some way.

SOAP and Our API operate in a very similar manner.

A Request

XML Generated via PHP5 SOAP client

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:localhost-paint" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns2="http://xml.apache.org/xml-soap" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body>
     <ns1:handleRequest>
       <contextId xsi:nil="true"/>
       <className xsi:type="xsd:string">bus_facade_context</className>
       <processName xsi:type="xsd:string">login</processName>
       <entityData xsi:type="ns2:Map">
         <item>
           <key xsi:type="xsd:string">userName</key>
           <value xsi:type="xsd:string">API USERNAME HERE</value>
         </item>
         <item>
           <key xsi:type="xsd:string">password</key>
           <value xsi:type="xsd:string">API PASSWORD HERE</value>
         </item>
       </entityData>
       <processData xsi:nil="true"/>
     </ns1:handleRequest>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
A SOAP message is made up of at the very least an envelope and body. The envelope informs the recieving parser that this is a SOAP message, and the first element to note is that this SOAP request uses the namespace illustrated by the WSDL:
xmlns:ns1="urn:localhost-paint"
Looking at the body of the SOAP request, the handleRequest generic function is being called with a series of named parameters.

The CONTEXTID that holds a session together is being generated by this request (as shown in the response) by adding the context entity for this API login to the bean store, therefore this is omitted by this request. However all subsequent requests will require this value to be provided as a reference
<contextId xsi:nil="true"/>
The FACADE bean, or CLASSNAME that is being handled is the context, used for generating and completing a session.
<className xsi:type="xsd:string">bus_facade_context</className>
The PROCESS (method) that is being called is unique to this FACADE and is called login.
<processName xsi:type="xsd:string">login</processName>
The ENTITY DATA (parameters) that are used to update, and are loaded onto the ENTITY bean (as all logins are tracked) is an associative array (map) containing the API username and password
<entityData xsi:type="ns2:Map">
     <item>
        <key xsi:type="xsd:string">userName</key>
        <value xsi:type="xsd:string">API USERNAME HERE</value>
     </item>
     <item>
        <key xsi:type="xsd:string">password</key>
        <value xsi:type="xsd:string">API PASSWORD HERE</value>
     </item>
</entityData>
There is no PROCESS DATA being passed in this request as the FACADE bean doesn't require any additional data that isn't loaded on to the ENTITY bean
    <processData xsi:nil="true"/>

A Response

    <?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:localhost-paint" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns2="http://xml.apache.org/xml-soap" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
 <SOAP-ENV:Body>
  <ns1:handleRequestResponse>
   <Result xsi:type="ns2:Map">
    <item>
     <key xsi:type="xsd:string">result</key>
     <value xsi:type="xsd:string">success</value>
    </item>
    <item>
     <key xsi:type="xsd:string">resultData</key>
     <value xsi:type="ns2:Map">
      <item>
          <key xsi:type="xsd:string">bus_entity_context</key>
          <value xsi:type="ns2:Map">
            <item>
                <key xsi:type="xsd:string">userName</key>
                <value xsi:type="xsd:string">API USERNAME LOGGED IN WITH</value>
            </item>
            <item>
              ......
            </item>
            <item>
              <key xsi:type="xsd:string">beanId</key>
              <value xsi:type="xsd:string">C-XPzaXk6LndjcI9D99dCnIUZ</value>
            </item>
            <item>
              .....
            </item>
          </value>
        </item>
      </Result>
   </ns1:handleRequestResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Looking at the body of the SOAP response, the handleRequestResponse contains a single object (an associative array) map called Result with two primary key values.

The RESULT contains either success if the request was successfully processed, or the type of the error that occurred during the request, for instance "bean_exception_validation".

    <key xsi:type="xsd:string">result</key>
<value xsi:type="xsd:string">success</value>

The RESULTDATA contains vital information from the response, either the desired response data, in this instance the beanId or some information regarding the error response.

    <key xsi:type="xsd:string">resultData</key>
<value xsi:type="ns2:Map">
    <item>
        <key xsi:type="xsd:string">bus_entity_context</key>
        <value xsi:type="ns2:Map">
            <item>
                <key xsi:type="xsd:string">userName</key>
                <value xsi:type="xsd:string">API USERNAME LOGGED IN WITH</value>
            </item>
            <item>
              ......
            </item>
            <item>
              <key xsi:type="xsd:string">beanId</key>
              <value xsi:type="xsd:string">C-XPzaXk6LndjcI9D99dCnIUZ</value>
            </item>
            <item>
              .....
            </item>
          </value>
    </item>
</value>

In this example a lot of the RESULTDATA in the response has been removed for clarity purposes, as the entire entity bean represented as an array is returned from the request, and that isn't required in this case to illustrate how the requests and responses are formed or operate.

In subsequent requests the beanId from this response is the reference to the session, the contextId.