SOAP is a messaging protocol; REST is an architectural style. Both let applications communicate through APIs. SOAP standardizes message structure and processing. REST (Representational State Transfer) organizes interactions around resources and their representations. See the SOAP specification and REST's original definition.
The same task, two interfaces
Imagine a shopping app asking for order 123. These illustrative HTTPS exchanges omit routine headers.
SOAP: send a structured message
A SOAP service might expose GetOrder. The client sends an XML message inside a standardized SOAP 1.2 envelope:
POST /OrderService HTTP/1.1
Host: api.example.com
Content-Type: application/soap+xml; charset=utf-8
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:ord="https://example.com/orders">
<soap:Body>
<ord:GetOrder>
<ord:Id>123</ord:Id>
</ord:GetOrder>
</soap:Body>
</soap:Envelope>
The server replies with another SOAP envelope containing the result or a Fault. Envelope and Body belong to SOAP; GetOrder belongs to this application. SOAP also supports document exchanges without remote function calls. W3C SOAP primer
REST over HTTP: retrieve a resource representation
The order has a resource URL. The HTTP method expresses the action:
GET /orders/123 HTTP/1.1
Host: api.example.com
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"id": 123,
"status": "shipped"
}
The JSON is a representation of the order. A typical API could expose these actions:
GET /orders/123 → Read the order
POST /orders → Create an order
PATCH /orders/123 → Update part of the order
DELETE /orders/123 → Delete the order
These routes apply standard HTTP method semantics, including PATCH for partial modifications. Creation is one use of POST; it also supports other resource-specific processing.
Quick comparison
| Aspect | SOAP | REST over HTTP |
|---|---|---|
| Format | XML-based envelope | Often JSON; other formats allowed |
| Typical interaction | Named operations or document messages | Resources accessed through HTTP methods |
| Interface description | Commonly WSDL and XML Schema | Can use OpenAPI and schemas |
| Transport | HTTP or another SOAP protocol binding | HTTP for web APIs |
| Complexity | Additional envelope and messaging machinery | Often simpler with standard HTTP tooling |
WSDL describes a service's operations, messages, and endpoints. OpenAPI can provide a formal contract for an HTTP API too. Neither description format guarantees a good API design.
Useful distinctions
- REST does not mean JSON. XML, HTML, and other representations are possible.
- Stateless does not mean no database. Each request carries enough context to be understood independently; the server can still store orders. See REST's constraints.
- REST includes more than resource URLs. Its uniform interface includes links and controls that guide subsequent actions, called hypermedia. Fielding's explanation
- SOAP is not inherently more secure. Both can use HTTPS. SOAP also has WS-Security, which supports signing and encrypting message content; this requires implementation and configuration.
Which should I use?
As a practical starting point, consider REST for new web, mobile, and public APIs. Choose SOAP when an enterprise or partner integration requires its contract or messaging standards. Neither is universally better; compatibility and application requirements should drive the choice.
Comments