XML Web Services – SOAP

One of the most significant real-world applications of XML is in web services — systems that allow different software applications to communicate with each other over a network. XML is the backbone of one of the most widely adopted web service standards: SOAP (Simple Object Access Protocol).

Web services make it possible for a Java application on one server to call a function on a Python application on another server — and receive the response — regardless of platform, operating system, or programming language. XML ensures both sides speak the same language.

What is a Web Service?

A web service is a software system designed to support machine-to-machine communication over a network. Two main styles exist:

• SOAP Web Services: Use XML-based messages with a strict, formal structure. Common in enterprise and financial systems.
• REST Web Services: Use simpler HTTP requests and responses, often with JSON or XML. Most modern APIs use REST.

This topic focuses on SOAP, where XML plays a central and mandatory role.

What is SOAP?

SOAP stands for Simple Object Access Protocol. It defines a standard format for sending messages between applications over HTTP (or other protocols). Every SOAP message is written in XML and follows a specific envelope structure.

SOAP is used heavily in:

• Banking and financial services (payment processing, account information).
• Healthcare systems (exchanging patient data via HL7 standards).
• Enterprise resource planning (ERP) integrations.
• Government and legacy enterprise systems.

Structure of a SOAP Message

Every SOAP message is enclosed in a SOAP Envelope — the outermost element. Inside the envelope are two parts:

1. Header (optional): Contains metadata such as authentication credentials, transaction IDs, or routing information.
2. Body (required): Contains the actual message — either a request to a service or a response from it.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope 
  xmlns:soap="http://www.w3.org/2003/05/soap-envelope">

  <soap:Header>
    <!-- Optional metadata goes here -->
  </soap:Header>

  <soap:Body>
    <!-- The main message goes here -->
  </soap:Body>

</soap:Envelope>

SOAP Request Example

This example shows a SOAP request asking a weather service for the current temperature in a city:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope 
  xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:weather="http://api.weatherservice.com/">

  <soap:Header>
    <weather:AuthToken>abc123xyz</weather:AuthToken>
  </soap:Header>

  <soap:Body>
    <weather:GetTemperature>
      <weather:CityName>Tokyo</weather:CityName>
      <weather:Unit>Celsius</weather:Unit>
    </weather:GetTemperature>
  </soap:Body>

</soap:Envelope>

The request calls the GetTemperature operation, passing a city name and the desired unit. The header carries an authentication token.

SOAP Response Example

The service responds with another SOAP message containing the requested data:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope 
  xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:weather="http://api.weatherservice.com/">

  <soap:Body>
    <weather:GetTemperatureResponse>
      <weather:City>Tokyo</weather:City>
      <weather:Temperature>18</weather:Temperature>
      <weather:Unit>Celsius</weather:Unit>
      <weather:Condition>Partly Cloudy</weather:Condition>
    </weather:GetTemperatureResponse>
  </soap:Body>

</soap:Envelope>

SOAP Fault: Error Handling

When a SOAP request fails, the service sends back a SOAP Fault inside the body. The fault contains a code and a human-readable message explaining the error.

<soap:Body>
  <soap:Fault>
    <soap:Code>
      <soap:Value>soap:Sender</soap:Value>
    </soap:Code>
    <soap:Reason>
      <soap:Text xml:lang="en">
        City name is required and cannot be empty.
      </soap:Text>
    </soap:Reason>
  </soap:Fault>
</soap:Body>

WSDL — Describing SOAP Web Services

WSDL stands for Web Services Description Language. It is an XML-based file that describes everything about a SOAP web service: what operations it offers, what parameters they take, and what responses they return. WSDL acts as the contract between the service and its consumers.

Simplified WSDL Structure

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
             name="WeatherService"
             targetNamespace="http://api.weatherservice.com/">

  <message name="GetTemperatureRequest">
    <part name="CityName" type="xsd:string" />
    <part name="Unit" type="xsd:string" />
  </message>

  <message name="GetTemperatureResponse">
    <part name="Temperature" type="xsd:integer" />
    <part name="Condition" type="xsd:string" />
  </message>

  <portType name="WeatherPortType">
    <operation name="GetTemperature">
      <input message="GetTemperatureRequest" />
      <output message="GetTemperatureResponse" />
    </operation>
  </portType>

</definitions>

The WSDL file is typically published at a URL so that developers can discover and understand the service without needing separate documentation.

XML in REST APIs

While REST APIs today most commonly use JSON, XML is still supported and used in many REST services. A REST API that accepts or returns XML follows the same well-formed XML rules.

Example: REST Request Sending XML

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <username>alex99</username>
  <email>alex@example.com</email>
  <role>editor</role>
</user>

Example: REST Response in XML

HTTP/1.1 201 Created
Content-Type: application/xml

<response>
  <status>success</status>
  <userId>USR-00452</userId>
  <message>User created successfully.</message>
</response>

SOAP vs REST — A Quick Comparison

Key Points

• SOAP is an XML-based protocol for structured communication between applications over a network.
• Every SOAP message has an Envelope containing an optional Header and a required Body.
• SOAP Fault elements communicate errors back to the calling application.
• WSDL describes a SOAP web service's operations, inputs, and outputs in XML format.
• REST APIs can also use XML as their data format, though JSON is more common today.
• SOAP is preferred in enterprise environments where security, reliability, and strict contracts are required.