SOAP is known as the Simple Object Access Protocol, but in later times was just shortened to SOAP v1.2. SOAP is a protocol or in other words, is a definition of how web services talk to each other or talk to client applications that invoke them.

SOAP is an XML-based protocol for accessing web services over HTTP. It has some specifications that could be used across all applications.

SOAP was developed as an intermediate language so that applications built on various programming languages could talk easily to each other and avoid the extreme development effort.

In this tutorial, you will learn –

One of the methods used to combat this complexity is to use XML (Extensible Markup Language) as the intermediate language for exchanging data between applications.

Every programming language can understand the XML markup language. Hence, XML was used as the underlying medium for data exchange.

But there are no standard specifications on use of XML across all programming languages for data exchange. That is where SOAP software comes in.

SOAP was designed to work with XML over HTTP and have some sort of specification which could be used across all applications. We will look into further details on the SOAP protocol in the subsequent chapters.

SOAP Building Blocks

The SOAP specification defines something known as a “SOAP message” which is what is sent to the web service and the client application.

The below diagram of SOAP architecture shows the various building blocks of a SOAP Message.

The SOAP message is nothing but a mere XML document which has the below components.

• An Envelope element that identifies the XML document as a SOAP message – This is the containing part of the SOAP message and is used to encapsulate all the details in the SOAP message. This is the root element in the SOAP message.
• A Header element that contains header information – The header element can contain information such as authentication credentials which can be used by the calling application. It can also contain the definition of complex types which could be used in the SOAP message. By default, the SOAP message can contain parameters that could be of simple types such as strings and numbers, but can also be a complex object types.

A simple SOAP service example of a complex type is shown below.

Suppose we wanted to send a structured data type that had a combination of a “Sample Name” and a “Sample Description,” then we would define the complex type as shown below.

The complex type is defined by the element tag <xsd:complexType>. All of the required elements of the structure along with their respective data types are then defined in the complex type collection.

<xsd:complexType>     
 <xsd:sequence>       
 	<xsd:element name="Name" type="string"/>         
  	<xsd:element name="Description"  type="string"/>
  </xsd:sequence>
</xsd:complexType>

A Body element that contains call and response information – This element is what contains the actual data which needs to be sent between the web service and the calling application. Below is an SOAP web service example of the SOAP body which actually works on the complex type defined in the header section. Here is the response of the Name and Description that is sent to the calling application which calls this web service.

<soap:Body>
   <GetInfo>
		<Name>Web Services</Name> 
		<Description>All about web services</Description> 
   </GetInfo>
</soap:Body>

SOAP Message Structure

One thing to note is that SOAP messages are normally auto-generated by the web service when it is called.

Whenever a client application calls a method in the web service, the web service will automatically generate a SOAP message which will have the necessary details of the data which will be sent from the web service to the client application.

As discussed in the previous topic of this SOAP tutorial, a simple SOAP Message has the following elements –

• The Envelope element
• The header element and
• The body element
• The Fault element (Optional)

Let’s look at an example below of a simple SOAP message and see what element actually does.

1. As seen from the above SOAP message, the first part of the SOAP message is the envelope element which is used to encapsulate the entire SOAP message.
2. The next element is the SOAP body which contains the details of the actual message.
3. Our message contains a web service which has the name of “SampleWebService”.
4. The “SampleWebservice” accepts a parameter of the type ‘int’ and has the name of ID.

Now, the above SOAP message will be passed between the web service and the client application.

You can see how useful the above information is to the client application. The SOAP message tells the client application what is the name of the Web service, and also what parameters it expects and also what is the type of each parameter which is taken by the web service.

SOAP Envelope Element

The first bit of the building block is the SOAP Envelope.

The SOAP Envelope is used to encapsulate all of the necessary details of the SOAP messages, which are exchanged between the web service and the client application.

The SOAP envelope element is used to indicate the beginning and end of a SOAP message. This enables the client application which calls the web service to know when the SOAP message ends.

The following points can be noted on the SOAP envelope element.

• Every SOAP message needs to have a root Envelope element. It is absolutely mandatory for SOAP message to have an envelope element.
• Every Envelope element needs to have at least one soap body element.
• If an Envelope element contains a header element, it must contain no more than one, and it must appear as the first child of the Envelope, before the body element.
• The envelope changes when SOAP versions change.
• A v1.1-compliant SOAP processor generates a fault upon receiving a message containing the v1.2 envelope namespace.
• A v1.2-compliant SOAP processor generates a Version Mismatch fault if it receives a message that does not include the v1.2 envelope namespace.

Below is an SOAP API example of version 1.2 of the SOAP envelope element.

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://www.w3.org/2001/12/soap-envelope" SOAP-ENV:encodingStyle=" http://www.w3.org/2001/12/soap-encoding">
          <soap:Body>
        <SampleWebService xmlns="http://tempuri.org/">
                  <ID>int</ID>
                </SampleWebService>
          </soap:Body>
</SOAP-ENV:Envelope>

The Fault message

When a request is made to a SOAP web service, the response returned can be of either 2 forms which are a successful response or an error response. When success is generated, the response from the server will always be a SOAP message. But if SOAP faults are generated, they are returned as “HTTP 500” errors.

The SOAP Fault message consists of the following elements.

1. <faultCode>– This is the code that designates the code of the error. The fault code can be either of any below values
   1. SOAP-ENV:VersionMismatch – This is when an invalid namespace for the SOAP Envelope element is encountered.
   2. SOAP-ENV:MustUnderstand – An immediate child element of the Header element, with the mustUnderstand attribute set to “1”, was not understood.
   3. SOAP-ENV:Client – The message was incorrectly formed or contained incorrect information.
   4. SOAP-ENV:Server – There was a problem with the server, so the message could not proceed.
2. <faultString> – This is the text message which gives a detailed description of the error.
3. <faultActor> (Optional)– This is a text string which indicates who caused the fault.
4. <detail>(Optional) – This is the element for application-specific error messages. So the application could have a specific error message for different business logic scenarios.

Example for Fault Message

An example of a fault message is given below. The error is generated if the scenario wherein the client tries to use a method called ID in the class GetInfo.

The below fault message gets generated in the event that the method does not exist in the defined class.

<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema">
      <SOAP-ENV:Body>
         <SOAP-ENV:Fault>
         <faultcode xsi:type="xsd:string">SOAP-ENV:Client</faultcode>
        <faultstring xsi:type="xsd:string">
            Failed to locate method (GetInfoID) in class (GetInfo)
         </faultstring>
    </SOAP-ENV:Fault>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Output:

When you execute the above code, it will show the error like “Failed to locate method (GetInfoID) in class (GetInfo)”

SOAP Communication Model

All communication by SOAP is done via the HTTP protocol. Prior to SOAP, a lot of web services used the standard RPC (Remote Procedure Call) style for communication. This was the simplest type of communication, but it had a lot of limitations.

Now in this SOAP API tutorial, let’s consider the below diagram to see how this communication works. In this example, let’s assume the server hosts a web service which provided 2 methods as

• GetStudent – This would get all Student details
• SetSTudent – This would set the value of the details like student’s course, year, batch, etc. accordingly.

In the normal RPC style communication, the client would just call the methods in its request and send the required parameters to the server, and the server would then send the desired response.

The above communication model has the below serious limitations

1. Not Language Independent – The server hosting the methods would be in a particular programming language and normally the calls to the server would be in that programming language only.
2. Not the standard protocol – When a call is made to the remote procedure, the call is not carried out via the standard protocol. This was an issue since mostly all communication over the web had to be done via the HTTP protocol.
3. Firewalls – Since RPC calls do not go via the normal protocol, separate ports need to be open on the server to allow the client to communicate with the server. Normally all firewalls would block this sort of traffic, and a lot of configuration was generally required to ensure that this sort of communication between the client and the server would work.

To overcome all of the limitations cited above, SOAP would then use the below communication model

1. The client would format the information regarding the procedure call and any arguments into a SOAP message and sends it to the server as part of an HTTP request. This process of encapsulating the data into a SOAP message was known as Marshalling.
2. The server would then unwrap the message sent by the client, see what the client requested for and then send the appropriate response back to the client as a SOAP message. The practice of unwrapping a request sent by the client is known as Demarshalling.

Advantages of SOAP

SOAP is the protocol used for data interchange between applications. Below are some of the reasons as to why SOAP is used.

• When developing SOAP based Web services, you need to have some of language which can be used for web services to talk with client applications. SOAP is the perfect medium which was developed in order to achieve this purpose. This protocol is also recommended by the W3C consortium which is the governing body for all web standards.
• SOAP is a light-weight protocol that is used for data interchange between applications. Note the keyword ‘light.’ Since SOAP programming is based on the XML language, which itself is a light weight data interchange language, hence SOAP as a protocol that also falls in the same category.
• SOAP is designed to be platform independent and is also designed to be operating system independent. So the SOAP protocol can work any programming language based applications on both Windows and Linux platforms.
• It works on the HTTP protocol –SOAP works on the HTTP protocol, which is the default protocol used by all web applications. Hence, there is no sort of customization which is required to run the web services built on the SOAP protocol to work on the World Wide Web.