SOAP APIs
📜 SOAP APIs
What SOAP Actually Is
SOAP stands for Simple Object Access Protocol — somewhat ironically, given it's rarely described as "simple" in practice. Unlike REST, which is an architectural style with no formal specification (Chapter 3), SOAP is an actual protocol: a strictly defined XML-based message format, standardized by the W3C, most commonly sent over HTTP but technically transport-agnostic (it can run over SMTP or other transports too). It originated at Microsoft and IBM in the late 1990s, aimed squarely at enterprise systems that needed strict contracts and strong typing more than they needed lightweight flexibility.
The SOAP Envelope
Every SOAP message — request or response — is wrapped in an Envelope, containing an optional Header (metadata like authentication or session tokens) and a required Body (the actual request or response payload), all expressed as XML:
A SOAP Request: GetWeather
Compare that to Chapter 2's plain JSON weather example — the same underlying idea (ask for London's weather), but SOAP wraps it in a much more formal, verbose structure, with the envelope/header/body pattern present on every single message, request or response.
WSDL: The Formal Contract
WSDL (Web Services Description Language) is where SOAP's real strength lies: an XML document describing exactly what operations a service offers, what parameters each one takes, what types they are, and what it returns — a strict, machine-readable contract. Tools can read a WSDL file and auto-generate fully-typed client code in languages like Java or C#, catching mismatches (wrong type, missing field) at code-generation time rather than discovering them as a runtime surprise.
No Formal Contract vs. a Formal Contract
REST
No enforced contract — documentation might describe the shape of a request/response, but nothing stops a server from silently changing a field's type or a client from sending malformed data. (OpenAPI/Swagger, covered in express2-7, adds documentation on top, but it's optional and not enforced by the protocol itself.)
SOAP + WSDL
The WSDL contract is the source of truth: exact operation names, exact parameter types, exact return shapes — generated client/server code is built directly from it, so mismatches tend to surface immediately rather than silently in production.
SOAP Faults: Error Handling the SOAP Way
SOAP doesn't lean on HTTP status codes the way REST does (Chapter 2) — errors are represented inside the XML body itself, as a SOAP Fault:
A SOAP Fault
Why Enterprise, Banking, and Government Systems Still Use SOAP
This isn't just legacy inertia (though that's certainly part of it — enormous amounts of core banking and government software were already built on SOAP long before REST was popular, and rewriting it is expensive and risky). SOAP also has genuine, deliberate advantages for certain domains:
WS-Security
A standard for message-level security — parts of the message itself can be encrypted or signed independently, rather than relying solely on transport-level encryption (contrast with the HTTPS/TLS course's transport-only approach).
Reliable Messaging & Transactions
Standards like WS-ReliableMessaging and WS-AtomicTransaction give formal guarantees about exactly-once delivery and multi-step transactional consistency — exactly what a bank-to-bank wire transfer needs, and something REST has no built-in equivalent for.
SOAP vs REST: The Real Tradeoffs
| Aspect | SOAP | REST |
|---|---|---|
| Contract | Formal, enforced (WSDL) | Informal, optional (OpenAPI/Swagger) |
| Message format | XML only | Usually JSON, but flexible |
| Payload size | Heavier, more verbose | Lighter |
| Built-in security/transactions | WS-Security, WS-*ReliableMessaging/Transaction standards | None built in — handled at the application layer |
| Best fit | Enterprise/banking/government systems needing strict guarantees | Public web/mobile APIs prioritizing simplicity and flexibility |
💻 Coding Challenges
Challenge 1: Read a SOAP Envelope
Given this chapter's GetWeather SOAP request example, identify what's in the Header versus the Body, and state exactly what operation is being invoked.
Goal: Practice reading a SOAP envelope's structure without getting lost in the XML verbosity.
Challenge 2: WSDL vs No Contract
A developer accidentally sends a string where an integer is expected. Explain what a WSDL-generated SOAP client would do differently from a plain, undocumented REST call in this situation, and at what point each would catch the mistake.
Goal: Practice explaining WHY a formal contract changes WHEN an error surfaces, not just THAT it does.
Challenge 3: SOAP or REST?
Recommend SOAP or REST for (a) a bank-to-bank wire transfer system requiring guaranteed-exactly-once delivery and formal contracts, and (b) a public weather API meant to be consumed easily by mobile app developers. Justify each choice.
Goal: Practice applying this chapter's tradeoff table to concrete, different scenarios.
Coming from REST, it's natural to assume "if the status code says success, the request succeeded." SOAP doesn't always work that way — because SOAP puts errors inside the XML body as a soap:Fault rather than relying on the HTTP status code, some SOAP implementations return a perfectly normal HTTP 200 OK even when the actual operation failed, with the failure only visible if you parse the body and check for a Fault element. Code that only checks the HTTP status code and assumes success can completely miss a genuine application-level error. Always parse the body of a SOAP response and check for a fault, regardless of what the HTTP status line says.
🎯 What's Next
The next chapter covers RPC-Style APIs: JSON-RPC, XML-RPC, and the Road to gRPC — simpler alternatives to SOAP that skip the heavy envelope/WSDL machinery while keeping the "call a specific function" mental model, and how that idea evolves into gRPC (which has its own full course on this site).