SOAP 101

A practical, hands-on guide to understanding and working with SOAP web services using Python. This series grew out of real experience integrating with enterprise systems — banking APIs, government data feeds, and legacy ERP platforms — where SOAP is not optional but mandatory.

Why This Series?

When I first encountered SOAP as a developer coming from a REST background, my first instinct was frustration. "Why is this XML so verbose? Why do I need a WSDL? Why can't they just do REST?" That mindset cost me time and led to poor integrations.

Once I understood why SOAP was designed the way it was — strict contracts, built-in security at the message level, formal operation definitions — the frustration turned into appreciation. SOAP is not dead. It is alive and running critical infrastructure in banking, healthcare, insurance, and government systems. If you integrate with enterprise software, you will encounter it.

This series documents everything I learned working with SOAP — from decoding cryptic WSDL files and building Python clients, to standing up a SOAP service and securing messages with WS-Security.

What You'll Learn

• Understand SOAP message structure: Envelope, Header, Body, and Fault

• Read and interpret WSDL service contracts

• Build SOAP service servers with Python using spyne

• Consume SOAP services from Python using zeep

• Define and validate XML Schema (XSD) data types

• Secure SOAP messages with WS-Security (UsernameToken, TLS)

• Handle SOAP Faults and build robust error recovery

• Test SOAP services with pytest and integration harnesses

• Bridge SOAP to REST for modern frontend consumption

Technology Stack

• Language: Python 3.11+

• SOAP Server: spyne — Python SOAP/WSDL framework

• SOAP Client: zeep — Modern Python SOAP client

• XML Processing: lxml

• Web Server: Flask (for hosting spyne services over HTTP)

• Security: zeep.wsse (WS-Security), Python cryptography

• Testing: pytest, responses, pytest-mock

• Validation: xmlschema

Prerequisites

• Python fundamentals (functions, classes, decorators)

• Basic understanding of XML

• Familiarity with HTTP and web APIs

• Virtualenv or pip package management

Series Structure

Part 1: Introduction to SOAP and XML Message Structure

Understand what SOAP is, why it exists, and how its XML message format works. Compare SOAP with REST and gRPC to know when to use each.

Key Topics:

• SOAP history and design goals

• SOAP Envelope, Header, Body, and Fault

• SOAP 1.1 vs SOAP 1.2

• RPC vs Document style

• Literal vs Encoded use

• Setting up Python environment (spyne, zeep, lxml)

---

Part 2: WSDL and Service Contracts

Learn how to read and write WSDL files — the formal contract that describes a SOAP service's operations, messages, and bindings.

Key Topics:

• WSDL structure: definitions, types, messages, portType, binding, service

• XSD type definitions inside WSDL

• Reading an existing WSDL with zeep

• Generating a WSDL from spyne service definitions

• Common WSDL patterns you will encounter in the wild

---

Part 3: Building SOAP Services with Python and spyne

Build a working SOAP service from scratch. Define operations, complex types, and expose the service over HTTP.

Key Topics:

• Defining a ServiceBase class with spyne

• Declaring operations with @rpc decorator

• Modeling complex types with ComplexModel

• Hosting the service with Flask

• Testing with SoapUI or Python clients

---

Part 4: SOAP Client Development with zeep

Consume real SOAP services from Python. Work with complex types, handle authentication, and optimize client performance.

Key Topics:

• Loading WSDL and creating zeep clients

• Calling operations and mapping responses

• Handling complex nested types

• Session management and persistent connections

• Caching WSDL for production use

• Debugging with zeep transport logging

---

Part 5: WS-Security and Authentication

Secure SOAP messages at the transport and message level using WS-Security standards.

Key Topics:

• WS-Security overview (OASIS standard)

• UsernameToken with password digest

• SSL/TLS transport security

• Message signing with X.509 certificates

• Timestamp tokens to prevent replay attacks

• Configuring zeep.wsse in clients

---

Part 6: Error Handling and SOAP Faults

Handle SOAP Faults properly — both when building services that return structured errors and consuming services that fail.

Key Topics:

• SOAP Fault structure (faultcode, faultstring, faultactor, detail)

• SOAP 1.1 vs SOAP 1.2 Fault differences

• Raising typed faults in spyne

• Catching zeep.exceptions.Fault in clients

• Retry logic and circuit breaker patterns for SOAP

---

Part 7: Testing, Performance, and Integration Patterns

Test SOAP services thoroughly and integrate them into modern architectures through REST gateways and async patterns.

Key Topics:

• Unit testing spyne services with pytest

• Integration testing with a live zeep client

• Mocking SOAP responses in tests

• Performance: connection pooling, WSDL caching, payload optimisation

• SOAP-to-REST proxy patterns with Flask

• Logging and observability for SOAP traffic

---

Getting Started

# Create virtual environment
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# Install dependencies
pip install spyne zeep lxml flask pytest pytest-mock requests

# Verify installation
python -c "import spyne, zeep, lxml; print('Ready')"

Jump to Part 1 to begin.