SOAP protocol
SOAP (Simple Object Access Protocol) is an XML-based simple protocol for exchanging information in a decentralized or distributed environment
SOAP = HTTP + XML, SOAP request may be HTTP POST or HTTP GET request. HTTP POST requests specify at least two HTTP headers: Content-Type and Content-Length.
1. Message format
A SOAP message is an ordinary XML document that contains the following elements:
- Required Envelope element to identify this XML document as a SOAP message
- Optional Header element containing header information
- Required Body element, containing all call and response information
- An optional Fault element that provides information about an error that occurred while processing this message
SOAP syntax rules:
- SOAP messages must be encoded in XML
- SOAP messages must use the SOAP Envelope namespace
- SOAP messages must use the SOAP Encoding namespace
- SOAP messages cannot contain DTD references
- SOAP messages cannot contain XML processing instructions
Basic format of SOAP message:
<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">
<soap:Header>
...
...
</soap:Header>
<soap:Body>
...
...
<soap:Fault>
...
...
</soap:Fault>
</soap:Body>
</soap:Envelope>
SOAP Envelope Element
is the root element of the SOAP message. It defines XML documents as SOAP messages. The value of the xmlns:soap namespace is always http://www.w3.org/2001/12/soap-envelop
xmlns:soap namespace
SOAP messages MUST have an Envelope element associated with the namespace "http://www.w3.org/2001/12/soap-envelope". If a different namespace is used, the application will fail and discard this message.
encodingStyle property
SOAP's encodingStyle property is used to define the data type used in the document. This attribute can appear on any SOAP element and will be applied to the element's content and all child elements of the element. There is no default encoding for SOAP messages.
SOAP Header element
The optional SOAP Header element can contain application-specific information about the SOAP message (such as authentication, payment, etc.). If the Header element is provided, it must be the first child of the Envelope element, and there can only be one
All immediate children of the Header element must be namespace-qualified. E.g:
<?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"> <soap:Header> <m:Trans xmlns:m="http://www.w3school.com.cn/transaction/" soap:mustUnderstand="1">234</m:Trans> </soap:Header> ... ... </soap:Envelope>
The above example contains a header with a "Trans" element whose value is 234, and the value of the "mustUnderstand" attribute of this element is "1".
SOAP defines three properties in the default namespace ("http://www.w3.org/2001/12/soap-envelope"). The three properties are: actor, mustUnderstand, and encodingStyle. These attributes, defined in the SOAP header, define how the container handles the SOAP message.
actor properties
SOAP messages are propagated from a sender to a receiver by following the message path through different endpoints. Not all parts of a SOAP message are intended for delivery to the final endpoint of the SOAP message, but, on the other hand, may be intended for delivery to one or more endpoints along the message path. The SOAP actor attribute can be used to address the Header element to a specific endpoint. E.g:
<?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"> <soap:Header> <m:Trans xmlns:m="http://www.w3school.com.cn/transaction/" soap:actor="http://www.w3school.com.cn/appml/"> 234 </m:Trans> </soap:Header> ... ... </soap:Envelope>
mustUnderstand property
SOAP's mustUnderstand attribute can be used to identify whether a header item is mandatory or optional for the recipient to process it. If you add "mustUnderstand="1" to a child element of the Header element, it indicates that the receiver processing the header must recognize the element. If the receiver cannot recognize the element, when processing the header must fail.
encodingStyle property
SOAP's encodingStyle property is used to define the data type used in the document. This attribute can appear on any SOAP element and will be applied to the element's content and all child elements of the element. There is no default encoding for SOAP messages.
SOAP Body element
The required SOAP Body element can contain the actual SOAP message intended for delivery to the message's final endpoint. Direct child elements of the SOAP Body element can be qualified namespaces. SOAP defines an element inside the Body element in the default namespace ("http://www.w3.org/2001/12/soap-envelope"). That is, the Fault element of SOAP, which is used to indicate an error message.
For example, there is a request:
<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">
<soap:Body>
<m:GetPrice xmlns:m="http://www.w3school.com.cn/prices">
<m:Item>Apples</m:Item>
</m:GetPrice>
</soap:Body>
</soap:Envelope>
Then the corresponding response should be like this:
<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">
<soap:Body>
<m:GetPriceResponse xmlns:m="http://www.w3school.com.cn/prices">
<m:Price>1.90</m:Price>
</m:GetPriceResponse>
</soap:Body>
</soap:Envelope>
SOAP Fault element
The optional SOAP Fault element is used to indicate the error message. If the Fault element has been provided, it must be a child of the Body element. The Fault element can appear only once in a SOAP message. Fault has the following child elements:
| child element | describe |
| <faultcode> | Codes for identifying faults |
| <faultstring> | Human-readable description of the failure |
| <faultactor> | Information on who caused the failure |
| <detail> | Persist application-specific error messages involving the Body element |
faultcode value:
| error code | describe |
| VersionMismatch | Invalid namespace for SOAP Envelope element was found |
| MustUnderstand | A direct child of the Header element (with the mustUnderstand attribute set to "1") is not understood. |
| Client | The message was incorrectly composed, or contained incorrect information. |
| Server | There is a problem with the server, so the process cannot proceed. |