Introducing SOAP Web Services (2024)

The Anatomy of SOAP-Based Web Services

Published in

DevOps.dev

11 min read

XML

XML stands for “Extensible Markup Language.” It is a markup language, much like HTML, but while HTML is designed to display data and focus on how data looks, XML is designed to store and transport data, focusing on what data is.

XML documents are made up of elements, which are defined by start and end tags. Elements can contain other elements, and they can also contain attributes. Attributes are used to provide additional information about an element.

<?xml version="1.0" encoding="UTF-8"?>
<students>
 <student>
 <name>Alice</name>
 <age>10</age>
 </student>
 <student>
 <name>Bob</name>
 <age>11</age>
 </student>
</students>

Each student is represented by a student element. The student element contains two child elements: name and age. The name and age elements contain the student's name and age, respectively.

API vs Web Services

API stands for Application Programming Interface. It is a set of rules and specifications that define how software components should interact with each other. APIs are used to allow different software components to communicate with each other, regardless of the programming language they are written in or the platform they are running on.

The main difference between an API and a web service is that an API can be used to communicate between any two software components, while a web service is specifically designed to communicate over the internet.

In general, an API is a broader term that encompasses web services and other types of APIs. A web service is a type of API that is specifically designed to communicate over the internet.

Types of Web Services

There are two main types of web services:

SOAP web services are more complex to implement and use than RESTful web services, but they offer several advantages, such as security and reliability. RESTful web services are easier to implement and use, but they may not be as secure or reliable as SOAP web services.

Protocol

A protocol refers to a set of rules and conventions that dictate how data is transmitted and received over a network. Protocols define the formats, sequences, error-handling processes, and synchronization of communication, ensuring that devices on a network can understand and communicate with each other effectively.

Protocols are important because they ensure that devices can communicate with each other reliably and efficiently. Without protocols, devices would not be able to understand each other’s messages and would not be able to communicate effectively.

A protocol defines the structure of messages that are sent and received. It specifies how data should be formatted into packets and the order in which packets should be sent and received.

They often have mechanisms to detect and handle errors during communication. For example, if data is not received correctly, the protocol might have rules to request that the data be sent again.

Protocols can dictate how a communication session should begin or end. For instance, they can specify the steps to establish or terminate a connection.

They include security features, such as encryption and authentication, to ensure data integrity and confidentiality.

Some protocols outline how data can be compressed for faster transmission and then decompressed upon receipt.

There are many different types of protocols, each with its specific purpose. Some common examples of protocols include:

HTTP: HTTP, or Hypertext Transfer Protocol, is the protocol used to transfer web pages and other resources over the internet.
TCP/IP: TCP/IP, or Transmission Control Protocol/Internet Protocol, is a protocol suite used to connect devices on the internet.
SMTP: SMTP, or Simple Mail Transfer Protocol, is the protocol used to send email messages.
FTP: FTP, or File Transfer Protocol, is the protocol used to transfer files between computers.
SSH: SSH, or Secure Shell, is a protocol used to establish a secure connection between two computers.

SOAP is an XML-based protocol that uses the HTTP protocol to exchange messages.

SOAP, or Simple Object Access Protocol, emerged in the late 1990s, primarily driven by Microsoft, as a pivotal tool for web services and distributed computing. Initially preceded by “XML-RPC”, the first official version of SOAP, termed SOAP 0.9, was launched in 1998. By 2000, SOAP 1.1 was presented to the World Wide Web Consortium (W3C), marking its widespread adoption. This was further solidified with the release of SOAP 1.2 in 2003, which brought enhanced error handling and clarity.

However, post-2003, SOAP’s dominance was challenged by the rise of REST (Representational State Transfer), a simpler alternative for web services. While REST has since become a favorite, especially for public web APIs, SOAP remains influential in sectors like finance and healthcare, where its structured standards are crucial. In a nutshell, SOAP pioneered web communications, and despite evolving tech trends, its impact remains significant.

Stateful Principle

A stateful service retains information from one session to the next, whereas a stateless service does not. The stateful principle can be essential for some applications where context or history is necessary to understand subsequent requests.

Stateful: The service retains data about client interactions over multiple requests. For example, if a client starts a transaction in one request and finishes it in a subsequent request, the SOAP service must remember the initial transaction’s details.

A customer logs into their online banking portal to view their balance.

The customer sends a SOAP request containing their account number and authentication details to inquire about the balance.
The banking server processes the request, retrieves the balance for the specified account number, and sends a SOAP response with the balance amount.
No session or transaction data from this interaction is stored after sending the response.

Stateless: Each request from a client to a server must contain all the information needed to understand and process the request. The server doesn’t retain any context between successive requests. This means the server doesn’t need to retain any session information or history. Each request is processed independently.

SOAP does not enforce statefulness or statelessness. Instead, it provides a framework where either can be implemented based on the application’s requirements.

The customer sends a SOAP request to start setting up a monthly bill payment. This request includes their account number, authentication details, and the intent to start a bill payment setup.
The banking server processes the request, initiates a new session for this multi-step transaction, and sends a SOAP response indicating that the session has started.
The server retains the session information and knows that this particular client is in the middle of setting up a bill payment.

Message Structure

A SOAP message is constructed using the format of an XML document. The message is structured around the <Envelope> element, which acts as the primary container or wrapper for the entire SOAP communication. Inside this envelope, there are typically two main components:

The <Header> element, which is optional, provides a space for supplementary information that might be beneficial for processing the message. This could include aspects such as authentication credentials, directives on how the message should be processed, or even specific routing information. However, since it's not mandatory, SOAP messages can be transmitted without the header, especially if these additional specifications aren't needed.
The <Body> element is where the main content of the SOAP message resides. This could be information related to the specific web service method being called, the parameters it requires, or the data being transferred. Think of it as the core payload or primary content of the communication.

Now, in scenarios where issues or errors arise during the processing of the SOAP message, there is a dedicated mechanism in place for communicating these errors back to the sender. This is achieved using the <Fault> element, which resides within the <Body>. The <Fault> element captures the specifics of the error, ensuring that the receiver is informed about the nature of the problem and can potentially take corrective measures or actions based on this feedback.

WSDL

WSDL stands for Web Services Description Language. It is an XML-based format used to describe the functionality offered by a web service. In essence, WSDL serves as a contract between the service provider and the service consumer, clearly defining what operations the service offers, the input and output parameters for each operation, data types, and protocols and conventions to be used.

Types defines the data types that will be used by the web service. WSDL uses XSD (XML Schema Definition) to define these data types.
Message defines the data elements for each operation. Each message can have one or more parts, which can be of a specific data type or can refer to the types defined in the “types” section.
Port Type describes the operations that can be performed and the messages involved in the operations. It’s analogous to function signatures in programming (i.e., method name, input parameters, and return values).
Binding specifies the protocol and data format for each port type. For instance, a service might be available via both SOAP 1.1 and SOAP 1.2 protocols, and these details would be specified in the bindings.
Service Ports define the actual endpoint or URL where the web service can be accessed. Each service can have multiple ports (endpoints) associated with it, representing different bindings or addresses.

Python Code

We can use the requests library to make a SOAP request.

import requests
# SOAP request URL
url = "http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso"# structured XML
payload = """<?xml version=\"1.0\" encoding=\"utf-8\"?>
 <soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\">
 <soap:Body>
 <CountryIntPhoneCode xmlns=\"http://www.oorsprong.org/websamples.countryinfo\">
 <sCountryISOCode>TR</sCountryISOCode>
 </CountryIntPhoneCode>
 </soap:Body>
 </soap:Envelope>"""
# headers
headers = {
 'Content-Type': 'text/xml; charset=utf-8'
}
# POST request
response = requests.request("POST", url, headers=headers, data=payload)
print(response)
print(response.text)
"""
<Response [200]>
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
 <m:CountryIntPhoneCodeResponse xmlns:m="http://www.oorsprong.org/websamples.countryinfo">
 <m:CountryIntPhoneCodeResult>90</m:CountryIntPhoneCodeResult>
 </m:CountryIntPhoneCodeResponse>
 </soap:Body>
</soap:Envelope>
"""

The URL points to the SOAP web service endpoint. In this case, it’s a service that offers information about countries.

Payload is structured as an XML document. It’s crafted to request the international phone code for the country with ISO code “TR” (which is Turkey). This XML structure adheres to the SOAP standards and is specific to the web service’s requirements. The CountryIntPhoneCode tag indicates the type of information being requested.

The headers are essential to inform the server about the type of content you’re sending. Here, the content type is text/xml with charset=utf-8 encoding, which is standard for SOAP requests.

HTTP POST request is made to the specified URL with the headers and SOAP payload. SOAP requests typically use the HTTP POST method.

We can also utilize the zeep library for the same purpose.

pip install zeep

from zeep import Client# SOAP service WSDL (Web Services Description Language) URL
wsdl_url = "http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso?WSDL"
# Create a client using the WSDL
client = Client(wsdl_url)
# Fetch the international phone code for India (ISO code "IN")
result = client.service.CountryIntPhoneCode("TR")
# Print the result
print(result)
"""
90
"""

Pros

Standardized: SOAP is backed by significant standards organizations such as the World Wide Web Consortium (W3C), which lends it credibility and consistency.
Platform and Language Neutral: SOAP can be implemented in any language and on any platform, making it versatile for integrating diverse systems.
Robust Protocol: It supports advanced features like ACID-compliant transactions and security, making it suitable for complex operations.
Statefulness: SOAP can be made stateful if required, which can be useful for certain applications.

Cons

Verbosity: SOAP messages, being XML-based, tend to be larger in size, leading to greater bandwidth consumption and slower processing times compared to lighter protocols.
Complexity: SOAP can be seen as overkill for simple web services. Its heavy-weight nature, with a need for detailed XML parsing, can be a deterrent for simpler applications.
Tighter Coupling: The reliance on a predefined WSDL can sometimes lead to a tighter coupling between the client and service.

Usage Areas

The inherent robustness and reliability of SOAP make it an attractive choice for enterprise-level applications, especially in sectors like finance, healthcare, and telecommunications where data integrity, security, and consistent transactions are essential. Its platform neutrality means heterogeneous systems can be easily integrated.

However, for lightweight, rapid development, especially in the realm of public-facing APIs or mobile applications, the verbosity and complexity of SOAP might be seen as a drawback. This has led to the rise of RESTful services and JSON as a more straightforward alternative in such scenarios.