Explaining SOAP Basics

Objective

After completing this lesson, you will be able to Explaining SOAP basics.

SOAP Basics

Introduction to SOAP

SOAP is a transmission and packaging protocol standardized by the World Wide Web Consortium (W3C). This protocol is used to exchange structured and typed information and messages based on XML between applications in a decentralized, distributed environment such as the internet.

No particular transport protocol is specified for SOAP. For the most part, however, SOAP is connected to the HTTP transport protocol. This allows your applications to communicate with remote systems using standard internet protocols and to execute components on other systems. Another advantage of SOAP is that it is not dependent on a particular platform. SOAP is accepted and supported by all major software manufacturers.

The Structure of a SOAP Message

A SOAP message consists of an optional SOAP header and a mandatory SOAP body. Both elements are incorporated into the SOAP envelope.

The information contained within the blocks in the SOAP header provides details about how the SOAP message should be processed. You can find information about the required message routing or about authentication or authorization, for example.

The SOAP body contains the actual user data of the message (payload) in XML format.

SOAP Envelope

The SOAP envelope is the root element of a SOAP message and encloses all other elements. It is always represented by an element called Envelope and can occur as a root element only once in a SOAP message.

The namespace for formulating a SOAP message is defined using the xmlns attribute. The attribute points to the underlying XML schema. If the SOAP Version 1.1 specification is used for the SOAP message, the attribute value is set to http://schemas.xmlsoap.org/soap/envelope. A SOAP Version 1.2 message contains the entry http://www.w3.org/2003/05/soap-envelope as the attribute value.

XML namespaces are an easy way to assign unique element and attribute names in XML documents. Element and attribute names are linked with namespaces by URI references.

SOAP Header

The optional header can perform various tasks within a SOAP based communication to specify the behavior of the SOAP message. Information like authentication, payment, intermediaries, etc., can be stored in the SOAP header. If it is available, it must precede the mandatory SOAP body and must be included in the SOAP Envelope. Therefore, the SOAP header is the first child element of the Envelope element.

Attribute - mustUnderstand

The SOAP mustUnderstand attribute can be used to indicate whether a header entry is mandatory or optional for the recipient to process.

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 does not recognize the element, it will fail when processing the Header.

Syntax:

soap:mustUnderstand="0|1"

Example:

Code Snippet
Copy code
Switch to dark mode
12345678910111213
<?xml version="1.0"?>
 <soap:Envelope
xmlns:soap="http://www.w3.org/2003/05/soap-envelope/"
soap:encodingStyle="http://www.w3.org/2003/05/soap-encoding">

<soap:Header>
   <m:Trans xmlns:m="https://www.w3schools.com/transaction/"
   soap:mustUnderstand="1">234
   </m:Trans>
</soap:Header>
...
...
</soap:Envelope>

Attribute - actor

A SOAP message may travel from a sender to a receiver by passing different endpoints along the message path. However, not all parts of a SOAP message may be intended for the ultimate endpoint, instead, it may be intended for one or more of the endpoints on the message path.

Syntax:

soap:actor="URI"

Example:

Code Snippet
Copy code
Switch to dark mode
12345678910111213
<?xml version="1.0"?>
 <soap:Envelope
xmlns:soap="http://www.w3.org/2003/05/soap-envelope/"
soap:encodingStyle="http://www.w3.org/2003/05/soap-encoding">

<soap:Header>
   <m:Trans xmlns:m="https://www.w3schools.com/transaction/"
   soap:actor="https://www.w3schools.com/code/">234
   </m:Trans>
</soap:Header>
...
...
</soap:Envelope>

Attribute - encodingStyle

The encodingStyle attribute is used to define the data types used in the document. This attribute may appear on any SOAP element, and it will apply to that element's contents and all child elements.

A SOAP message has no default encoding. There are two encodings:

  • SOAP Encoding

    When SOAP encoding is used, the SOAP message contains data type information within the SOAP message. This makes serialization (data translation) easier since the data type of each parameter is denoted with the parameter. An application using SOAP encoding is focused on remote procedure calls and will likely use RPC message style.

  • Literal

    Data is serialized according to the W3C XML Schema. The SOAP message does not directly contain any data type information, just a reference (namespace) to the schema that is used. To perform proper serialization (data translation), both the sender and the receiver must know the schema and must use the same rules for translating data.

SOAP Body

The SOAP body is a mandatory element that contains the application-defined XML data being exchanged in the SOAP message. The body must be contained within the envelope and must follow any headers that might be defined for the message.

The required SOAP body element contains the actual SOAP message intended for the ultimate endpoint of the message.

Since the SOAP standard does not specify the inner structure of the body in more detail, the message format must be defined separately. This is done by defining the message styles. WSDL distinguishes between two message styles: document and RPC. The message style affects the contents of the SOAP body:

  • Document style:

    The SOAP body contains one or more child elements called parts. There are no SOAP formatting rules for what the body contains; it contains whatever the sender and the receiver agrees upon.

  • RPC style:

    RPC implies that SOAP body contains an element with the name of the method or operation being invoked. This element in turn contains an element for each parameter of that method/operation.

Example: RPC style / SOAP encoded

Code Snippet
Copy code
Switch to dark mode
12345678
<soap:envelope> 
    <soap:body>
        <myMethod>
            <x xsi:type="xsd:int">5</x>
            <y xsi:type="xsd:float">5.0</y>
        </myMethod>
    </soap:body>
</soap:envelope>

The SOAP message contains an operation name (myMethod). The method transports 2 parameters, x and y, which both specify its data type (int and float) through the type attributes.

There are 2 namespaces that are used here: xsi and xsd. Both are defined within the SOAP envelope (not shown in this example). The xsi namespace is the schema instance (http://www.w3.org/2001/XMLSchema-instance) and defines the type attribute (besides others), xsd is the schema namespace (http://www.w3.org/2001/XMLSchema), and it defines the meaning of the data types like int or float.

Example: RPC style / literal

Code Snippet
Copy code
Switch to dark mode
12345678
<soap:envelope>
    <soap:body>
        <myMethod>
            <x>5</x>
            <y>5.0</y>
        </myMethod>
    </soap:body>
</soap:envelope>

In contrast to SOAP encoding, the parameters x and y do not specify any data type within the SOAP message. The sender and the receiver must ‘know’ what data type the parameters are. Usually that information is available in the WSDL.

Document style / literal

Code Snippet
Copy code
Switch to dark mode
123456
<soap:envelope>
    <soap:body>
        <x>5</x>
        <y>5.0</y>
    </soap:body>
</soap:envelope>

Here, there is no method or operation name part of the body. Instead, the body directly contains the parameters. Also, there is no data type information that is contained in the SOAP message. Everything that appears within the body is defined in a schema.

Document style / SOAP encoded doesn't make any sense.

SOAP-Fault

If an error occurs during processing, the response to a SOAP message is a SOAP fault element in the body of the message, and the fault is returned to the sender of the SOAP message.

The SOAP fault mechanism returns specific information about the error, including a predefined code, a description, and the address of the SOAP processor that generated the fault.

<faultcode>

Namespace-conformant identification of the error that occurred. SOAP defines some standard error codes (SOAP fault codes) that can be used in this element to describe errors:

  • VersionMismatch: An invalid namespace was found in the SOAP envelope.

  • MustUnderstand: A header block with the mustUnderstand=“true” attribute was not understood by the message receiver. Using the optional standard header block Misunderstood, the SOAP fault provides concrete information about which header blocks were not understood in the message that was received.

  • Client: For example, invalid message or authentication missing.

  • Server: A processing error occurred on the server side.

<faultstring>

Short, readable description of the processing error in more detail.

<faultactor>

This element contains the unique identifier (URI) of the message processing node at which the error occurred if it is not the target node.

<detail>

This element is designed to contain information about application-specific errors that occurred during processing of the actual message (payload) in the SOAP body. Errors that are to be assigned to the header must be described in the error message header.

Fault entries that must conform to namespace conventions can also be added.

Log in to track your progress & complete quizzes