The Simple Object Access Protocol (SOAP) ^{1) 2)} provides an XML ^{3) 4)} based messaging system on top of the Hypertext Transfer Protocol (HTTP) ^{5) 6)} or Simple Mail Transfer Protocol (SMTP) ⁷⁾, and includes a system for exception handling (faults).

SOAP requests and responses have the same basic structure: a SOAP Envelope enclosing an optional SOAP Header, a SOAP Body and optional SOAP Fault(s). If using HTTP as the transport there may also be additional HTTP headers set (e.g. SOAPAction). The Body contains the payload of the message encoded as an XML document. In most cases a software library is used which deals with the details of how to construct and decode SOAP messages, however it is useful to have some familiarity with the structure of SOAP messages when debugging.

The SOAP messages exchanged between a service and client can be generated in a number of different forms depending on the SOAP style of the service.

• Document/encoded: not used
• Document/literal: message is formatted following a defined XML schema and thus can be validated
• RPC/encoded: message is wrapped in a element using the name of the operation, data is encoded independently of an XML schema and includes type information
• RPC/literal: message is wrapped in a element using the name of the operation and content follows a defined XML schema but the wrapping elements means data cannot be directly validated.

The SOAP style has implications for the choice of SOAP tool-kit used when accessing the Web Service, since tool-kits often support a sub-set of styles. Compatibility and interoperability guidelines, such as The Web Services Interoperability Organization (WS-I) Basic Profile ⁸⁾, often exclude the RPC/encoded style due to the diversity of possible encodings for a message. So many newer SOAP tool-kits have dropped support for RPC/encoded and there is a general move towards using the Document/literal or RPC/literal styles for new services. Older services are usually based on the RPC/encoded style, thus requiring careful selection of a SOAP tool-kit which supports this style.

For more details about SOAP styles see Which style of WSDL should I use?.

The EB-eye service uses document/literal messages (in fact they are document/literal wrapped), for example using the listDomains() operation results in the following messages being exchanged:

• Request:

  <soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ebis="http://www.ebi.ac.uk/EBISearchService">
     <soapenv:Header/>
     <soapenv:Body>
        <ebis:listDomains/>
     </soapenv:Body>
  </soapenv:Envelope>

• Reponse:

  <soap:Envelope
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <soap:Body>
        <ns1:listDomainsResponse xmlns:ns1="http://www.ebi.ac.uk/EBISearchService">
           <ns1:arrayOfDomainNames>
              <ns1:string>2can</ns1:string>
              <ns1:string>arrayexpress-experiments</ns1:string>
              <ns1:string>arrayexpress-genes</ns1:string>
  ...
              <ns1:string>uniref100</ns1:string>
              <ns1:string>uniref50</ns1:string>
              <ns1:string>uniref90</ns1:string>
           </ns1:arrayOfDomainNames>
        </ns1:listDomainsResponse>
     </soap:Body>
  </soap:Envelope>

SOAP faults are encoded using document/literal, for example a propagated Java exception caused by invalid parameters being passed to the operation:

<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Server</faultcode>
      <faultstring>Fault: java.lang.NullPointerException</faultstring>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

These messages were captured using soapUI.

The WSDbfetch service uses RPC/encoded messages, for example using the getFormatStyles(db, format) operation results in the following messages being exchanged:

• Request:

  <soapenv:Envelope
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:wsd="http://wsdbfetch.ws.jdbfetch.ebi.ac.uk">
     <soapenv:Header/>
     <soapenv:Body>
        <wsd:getFormatStyles soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
           <db xsi:type="xsd:string">uniprot</db>
           <format xsi:type="xsd:string">fasta</format>
        </wsd:getFormatStyles>
     </soapenv:Body>
  </soapenv:Envelope>

• Reponse:

  <soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <soapenv:Body>
        <ns1:getFormatStylesResponse
          soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
          xmlns:ns1="http://wsdbfetch.ws.jdbfetch.ebi.ac.uk">
           <getFormatStylesReturn
              soapenc:arrayType="xsd:string[3]"
              xsi:type="soapenc:Array"
              xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
              <getFormatStylesReturn xsi:type="xsd:string">default</getFormatStylesReturn>
              <getFormatStylesReturn xsi:type="xsd:string">html</getFormatStylesReturn>
              <getFormatStylesReturn xsi:type="xsd:string">raw</getFormatStylesReturn>
           </getFormatStylesReturn>
        </ns1:getFormatStylesResponse>
     </soapenv:Body>
  </soapenv:Envelope>

Since the format for a SOAP fault is defined as part of the specification, these are always encoded as document/literal, for example passing an incorrect database name to the getFormatStyles(db, format) operation of the WSDbfetch service raises an exception:

<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <soapenv:Fault>
         <faultcode>soapenv:Server.userException</faultcode>
         <faultstring>uk.ac.ebi.jdbfetch.exceptions.DbfParamsException: Database, uniprota , not found!</faultstring>
         <detail>
            <ns1:hostname xmlns:ns1="http://xml.apache.org/axis/">tomcat-2.ebi.ac.uk</ns1:hostname>
         </detail>
      </soapenv:Fault>
   </soapenv:Body>
</soapenv:Envelope>

These messages were captured using soapUI.

A range of generic mechanisms exist for describing SOAP Web Service APIs:

• Really Simple Web Service Descriptions (RSWS) ⁹⁾
• SOAP Service Description Language (SSDL) ¹⁰⁾
• Web Services Description Language Version 1.1 (WSDL) ¹¹⁾
• Web Services Description Language Version 2.0 (WSDL 2.0) ¹²⁾

Most SOAP Web Services have a WSDL based service description document, however WSDL 2.0 is seeing some adoption, for example in the specification of the SOAP binding for the SPARQL Protocol for RDF ¹³⁾.

The next section looks at WSDL 1.1 in more detail.