SOAP APIs in depth: envelopes, WSDL and when SOAP still wins

By Uxair Ijaz · 2026-11-06 · 9 min read

SOAP has been declared dead for two decades, and it is still moving billions of pounds a day through banks, airlines, telecoms and government systems. Whether you are integrating with one of those systems or inheriting one, this guide explains what SOAP actually is, why enterprises chose it, and what professionals choose today.

What SOAP is

SOAP (Simple Object Access Protocol — the name has outlived the joke) is a protocol: an XML message format with strict rules about structure, transport and processing. A SOAP message is an XML envelope with, at most, three parts:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <!-- optional: security tokens, transaction ids, routing -->
  </soap:Header>
  <soap:Body>
    <m:GetCityForecast xmlns:m="https://example.com/weather">
      <m:CityName>Berlin</m:CityName>
      <m:Country>Germany</m:Country>
    </m:GetCityForecast>
  </soap:Body>
</soap:Envelope>

The Envelope is mandatory; the Header carries infrastructure concerns (signatures, transaction context); the Body carries your actual call. Responses mirror the shape, and failures come back as a structured Fault instead of an HTTP error:

<soap:Body>
  <soap:Fault>
    <faultcode>soap:Client</faultcode>
    <faultstring>Unknown CityName: Berln</faultstring>
    <detail><m:ErrorCode>404-CITY</m:ErrorCode></detail>
  </soap:Fault>
</soap:Body>

soap:Client means you built a bad message; soap:Server means the provider failed. Cut the XML out of a real envelope and paste it into our XML formatter — it repairs missing brackets and stray text the same way our JSON tools do — and the WSDL-produced payloads become readable fast. To turn a SOAP payload into something your app can use, the XML to JSON converter keeps attributes and order intact.

WSDL: the contract

Every serious SOAP service ships a WSDL (Web Services Description Language) document — an XML file that fully describes the service: its operations, the exact XML each accepts, the address, and the transport.

That contract is SOAP's real feature. From a WSDL, tooling generates typed client stubs: point Visual Studio or wsimport at the bank's WSDL and you get a GetCityForecast(CityName, Country) method that throws typed exceptions. Nothing comparable ships in the box for REST — OpenAPI describes REST but generating a fully typed client still needs extra tooling.

The trade-off is symmetrical: the WSDL is rigid. Adding an optional field is a negotiation; changing a required one is a new version.

WS-*: why enterprises signed up

SOAP arrived when "just use HTTPS" was not a complete answer for enterprise requirements, so the ecosystem standardised the rest as WS-* extensions carried in the envelope header:

Banks and government integrations still mandate these because they solve problems TLS alone does not: a message signed with WS-Security stays verifiable when it is stored, forwarded, or read by three intermediaries along the way.

SOAP vs REST, honestly

When SOAP still wins, and what professionals choose

SOAP remains the mandatory choice when the other side says so: payment networks, airline distribution (the travel industry's EDIFACT/SOAP stacks), European government gateways, SAP and half of the telecom world. You do not convince a central bank to add a JSON endpoint. In those integrations professionals:

• generate the client from the WSDL rather than hand-building envelopes;
• isolate SOAP behind an internal adapter service, so the rest of the codebase speaks JSON;
• keep the XML tooling close — debugging a SOAP Fault by eye is misery.

For new designs, the profession has voted clearly: REST for public and partner APIs, gRPC for internal service-to-service where typed contracts and throughput matter, GraphQL where clients assemble their own views. SOAP is not chosen; it is complied with.

Calling a SOAP service by hand

Generated stubs hide the plumbing, but every developer should survive one raw call:

curl https://api.example.com/weather \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H "SOAPAction: \"https://example.com/weather/GetCityForecast\"" \
  --data @envelope.xml

The three failure modes you will hit, in order of frequency:

1. Namespace mismatches — your element is in the wrong XML namespace, so the server answers "operation not found" while looking right. Compare namespaces character by character.
2. Encoding — the envelope says UTF-8, the body contains a stray Latin-1 byte, and the parser rejects the whole document.
3. SOAPAction mismatch — the header must match the WSDL operation exactly, including casing.

The takeaway

SOAP is a protocol for environments that need machine-checked contracts, message-level security and guaranteed delivery — properties that banks were right to want. REST won the default because most APIs never needed the heavy machinery, and JSON made everything easier to read. Meet both on their own terms: generate your stubs and go home when it is SOAP; spend the saved energy on getting your REST responses right when it is not.