SOAP Is Not Dead
Every few years someone declares SOAP dead. Every few years enterprise developers integrating with banking APIs, government systems, insurance platforms, and healthcare infrastructure find out it is still very much alive. If your project requires a SOAP API integration, you need a developer who understands what that actually involves.
It is not complicated in the way modern distributed systems are complicated. It is complicated in a different way: rigid contracts, verbose XML, WS-Security headers, and a set of tooling assumptions that predate modern development workflows by 15 years.
Start With the WSDL
Every SOAP service exposes a WSDL (Web Services Description Language) file that defines the available operations, their input and output message types, and the endpoint URL. The WSDL is the contract. Before writing any code, read it carefully.
Things to look for in the WSDL:
- The binding style (document/literal wrapped is the most common modern style; RPC/encoded is older and less common but still appears)
- Whether the service uses WS-Security for authentication or a simpler username/password in the SOAP header
- Any custom namespaces that your client needs to include correctly
- The fault types defined for error responses
Most SOAP client generators (Visual Studio's "Add Service Reference", the wsdl.exe tool, or Java's wsimport) can consume a WSDL and generate typed client code. This is usually the right starting point. Hand-crafting SOAP envelopes from scratch is error-prone and unnecessary.
WS-Security: The Part That Causes the Most Problems
WS-Security is a standard for adding authentication and message-level encryption to SOAP requests. In practice it comes in several flavours, and the SOAP service you are integrating with may use any of them:
- UsernameToken: Username and password (optionally hashed) in the SOAP security header. The simplest case.
- X.509 certificate signing: The request is signed with a private key and the service verifies with your public certificate. Requires certificate management and correct canonicalization of the XML before signing.
- SAML tokens: Common in enterprise identity federation scenarios. Requires an STS (Security Token Service) to obtain the token before calling the SOAP service.
Certificate-based WS-Security is where most integration projects get stuck. The XML canonicalization must be exactly right, the certificate chain must be correct, and the timestamp validity window must be respected. Getting any of these wrong produces cryptic fault responses that are difficult to debug without the right tooling.
Handling SOAP Faults Correctly
SOAP errors are returned as SOAP Fault elements in the response body, not as HTTP error status codes. A 200 OK response can contain a SOAP Fault. This surprises developers who are used to REST, where HTTP status codes carry the error signal.
Your integration needs to check for SOAP Faults on every response, regardless of HTTP status code. The Fault element contains a faultcode (a structured code identifying the error category) and a faultstring (a human-readable description). Custom fault types defined in the WSDL carry additional structured error data.
Log the complete SOAP envelope on fault responses, not just the faultstring. The detail element often contains structured information that is critical for debugging.
Testing SOAP Integrations
SOAP APIs rarely have sandbox environments as polished as modern REST APIs. You may be testing against a shared staging environment, a production system with test accounts, or a mock you build yourself.
SoapUI is the standard tool for exploring and testing SOAP services. It can import a WSDL, generate sample requests, and validate responses against the schema. Use it to understand the service before writing a line of integration code.
For automated testing, record real request/response pairs from SoapUI and use them as fixtures. Testing against a live SOAP service in CI is fragile; testing against recorded fixtures is fast and reliable.
When to Use a Specialist
If your integration involves WS-Security with certificate signing, a complex WSDL with many message types, or a service with poor documentation, a developer who has done SOAP integrations before will save you weeks of debugging time. The patterns are learnable, but the tooling is unforgiving and the error messages are often unhelpful.
We have delivered SOAP API integrations for enterprise clients including a SOAP-based B2B data exchange for Brandon Porter and automation work for clients in the insurance and government sectors. Get in touch if you have a SOAP integration that needs to be done correctly.