SOAP, originally the Simple Object Access Protocol, is an XML-based messaging protocol for exchanging structured data between applications, most often over HTTP. Among APIs, it represents the contract-first, enterprise style of web services: every message is an XML envelope with a defined structure, and the operations a service offers are described formally in a WSDL document that client tools can turn into code.
SOAP 1.1 was published in 2000 and SOAP 1.2 became a W3C Recommendation in 2003, at which point the expanded name was dropped and SOAP became simply a name. Although REST API and GraphQL designs dominate new public interfaces, SOAP remains common in banking, insurance, telecommunications, healthcare and government systems where formal contracts and message-level security matter.
How a SOAP message is structured
Every SOAP message is a single XML document whose root element is the Envelope. Inside it, an optional Header carries metadata such as security tokens, transaction identifiers or routing information, and a mandatory Body carries the actual request or response payload. When processing fails, the Body contains a Fault element with a code, a human-readable reason and optional detail.
| Element | Required | Purpose |
|---|---|---|
| Envelope | Yes | Root element that declares the SOAP namespace and version |
| Header | No | Extension blocks for security, addressing and transactions |
| Body | Yes | Operation request, response data or a fault |
| Fault | Only on error | Standardized error code, reason and detail |
Header blocks can carry the attribute mustUnderstand, which obliges the receiver to reject the message if it does not know how to process that block. This mechanism lets intermediaries and endpoints add features without breaking older clients silently, and it is the basis on which the WS-* extension family was built.
WSDL contracts and the WS-* standards
A SOAP service is normally described by a Web Services Description Language file, usually WSDL 1.1. The WSDL defines the data types through XML Schema, the messages, the operations grouped into a port type, the binding to SOAP and HTTP and the network address of the service. Tools such as wsimport for Java or svcutil for .NET read the WSDL and generate typed client classes, so calling a remote operation looks like calling a local method.
Around this core, a set of OASIS and W3C specifications known as WS-* adds enterprise capabilities at the message level. They are optional, and many SOAP services use none of them, but they explain why SOAP survives in regulated industries.
| Specification | What it adds | Typical use |
|---|---|---|
| WS-Security | Signatures, encryption and tokens inside the message | Payment and identity services |
| WS-Addressing | Message IDs, reply-to and routing headers | Asynchronous and routed messaging |
| WS-ReliableMessaging | Delivery guarantees and ordering | Unreliable network links |
| WS-AtomicTransaction | Distributed transaction coordination | Cross-system financial updates |
| MTOM | Efficient binary attachments | Documents and images in messages |
The key distinction is message-level security versus transport-level security. HTTPS protects a message only between two connected endpoints, while WS-Security signs and encrypts parts of the XML itself, so protection survives when the message passes through queues, gateways or other intermediaries.
Binding styles and transports
SOAP is transport-independent in principle. HTTP POST is by far the most common binding, but specifications and products also support SMTP, JMS message queues and raw TCP. In SOAP 1.1 over HTTP, the target operation is indicated by the SOAPAction header and the content type is text/xml, whereas SOAP 1.2 uses application/soap+xml with an action parameter.
WSDL bindings also choose a style and encoding. The modern and interoperable choice is document/literal wrapped, in which the Body contains one element named after the operation and validated by XML Schema. The older RPC/encoded style, which used SOAP-specific encoding rules, is prohibited by the WS-I Basic Profile and appears mainly in legacy systems.
SOAP compared with other API styles
SOAP is best understood by contrast with the other API styles in use today, each of which makes different trade-offs between strictness, efficiency and ease of use. The table summarizes the most important differences.
| Aspect | SOAP | REST API | gRPC |
|---|---|---|---|
| Message format | XML envelope | Usually JSON | Protocol Buffers |
| Contract | WSDL, mandatory in practice | OpenAPI, optional | .proto file, mandatory |
| Operation model | Named operations | Resources and HTTP methods | Named remote procedures |
| Caching | Not supported by HTTP caches | Native HTTP caching | Not supported by HTTP caches |
| Security options | Transport and message level | Transport level, tokens | Transport level, tokens |
| Payload size | Large and verbose | Moderate | Compact binary |
Because nearly every SOAP call is an HTTP POST to a single endpoint, standard HTTP features such as caching, conditional requests and meaningful status codes are largely bypassed. REST uses those features directly, while gRPC trades XML verbosity for compact binary encoding and streaming over HTTP/2.
Practical strengths and limitations
SOAP is a sound choice when both sides need a strict, machine-checked contract, when messages must be signed for non-repudiation, or when an existing partner system offers nothing else. Its weaknesses show up in payload size, parsing cost and tooling friction, especially in browsers and lightweight mobile clients.
- Verbosity: the same data often takes several times more bytes in a SOAP envelope than in JSON.
- Version drift: regenerating clients after every WSDL change is mandatory, and small schema edits can break callers.
- Interoperability gaps: namespaces, optional elements and date formats are frequent sources of mismatches between vendors.
- XML security risks: parsers must disable external entities to prevent XXE attacks and limit entity expansion.
- Testing: tools such as SoapUI or generated stubs are usually needed instead of a simple command-line request.
Many organizations now place an API gateway in front of SOAP services to expose a JSON facade to new clients while keeping the original contract for existing partners. This approach protects legacy investments but adds a translation layer that must be maintained and tested whenever either side changes.
The simple explanation
SOAP is a way for two computer systems to send each other formal, standardized letters. Every letter goes in the same kind of envelope, with an optional cover sheet for stamps and signatures and a main page with the actual request. Both sides agree in advance on a detailed form that describes exactly which requests exist and what each one must contain.
This makes SOAP strict and predictable but heavy. It suits banks and government agencies that care more about precise agreements and signed messages than about speed or simplicity.
How it is used in practice
An insurance company connects its claims system to a national vehicle registry that publishes a SOAP service. The registry provides a WSDL file, and the insurer’s developers generate Java client classes from it in a few minutes. Each lookup sends a document/literal request containing a registration number, with a WS-Security header that carries a signed X.509 token identifying the insurer.
Because the signature covers the message itself, the registry can prove which insurer requested which record, even though the traffic passes through two gateways. When the registry later adds an optional field for vehicle color, the schema change is announced with a new WSDL, the insurer regenerates its classes during a scheduled release and existing calls continue to work because the new element is optional.