REST vs SOAP

Key Takeaways

• REST is an architectural style; SOAP is an XML-based messaging protocol. They describe different aspects of a service interface.
• REST means more than HTTP plus JSON: its constraints include stateless requests, caching, and a uniform, hypermedia-driven interface.
• SOAP does not automatically provide stronger security, reliable delivery, or ACID transactions. Additional specifications and implementation choices supply those capabilities.
• Choose based on contracts, client tooling, transport, caching, security requirements, and existing integrations. One project can use both.

Comparing SOAP to REST is comparing apples to oranges. SOAP is a protocol, while REST is an architectural style. REST constrains how components interact; SOAP defines a message structure and processing framework. The useful question isn't which is universally better, but which interface meets your requirements.

Don't reduce the choice to “REST is modern; SOAP is secure.” Start with the consumers, contracts, and operational guarantees your service actually needs.

What Is REST?

Representational State Transfer, or REST, was described in Roy Fielding's 2000 dissertation. Its six constraints are uniform interface, statelessness, cacheability, client-server separation, a layered system, and optional code on demand.

Uniform Interface

The uniform interface gives interactions shared rules instead of a different communication model for every operation. It has four parts:

• Resource identification: identify a resource, such as an order, separately from its representation.
• Manipulation through representations: exchange representations of resource state rather than expose server internals.
• Self-descriptive messages: provide the metadata needed to interpret a message, including its representation format and applicable processing rules.
• Hypermedia as the engine of application state: representations provide links or controls that guide the client's next actions. This is often abbreviated HATEOAS.

REST doesn't prescribe JSON. HTML, XML, and other representation formats can participate in the model; JSON endpoints alone don't establish REST conformance.

Stateless Requests

Each request carries the context needed to understand it, rather than depending on a remembered client conversation. Servers can still store orders, accounts, and other resource state. Supplying credentials and request context on each call reduces dependence on routing a client to one particular server process.

Cacheability

Responses indicate whether they can be reused. With HTTP, Cache-Control: max-age=60 specifies a freshness lifetime; ETag and If-None-Match support validation, potentially returning 304 Not Modified. private prevents shared-cache storage, no-cache requires validation before reuse, and no-store prohibits storage. These directives aren't interchangeable.

Client-Server Separation

Separate presentation concerns from service-side data management. Browser and mobile clients can share a backend without sharing its implementation, but the interface remains a compatibility boundary.

Layered System

A client interacts with its immediate layer, which might be a proxy, gateway, or cache rather than the origin server. Layers can isolate responsibilities, but add latency and limit visibility across boundaries.

Code on Demand, Optional

A server may extend client functionality by sending executable code, such as JavaScript. This is optional, not a requirement for every API response.

HTTP Methods Aren't Just CRUD Labels

CRUD—create, read, update, delete—is a useful starting analogy, not a definition of HTTP methods. Safe means the client doesn't request a state-changing action. Idempotent means repeating an identical request has the same intended server-side effect as sending it once.

The rules come from HTTP Semantics and the separate PATCH specification. PATCH behavior also depends on the patch format and operation.

This illustrative semantics sketch isn't executable HTTP:

GET /orders/123
  Read the order; don't cancel it.

PUT /preferences/theme  {"theme":"dark"}
  Repeating the same request preserves the same intended state.

DELETE /orders/123
  An initial 204 and a later 404 can still be idempotent.

POST /orders/search  {"status":"paid"}
  Process a search; POST doesn't necessarily create a resource.

Idempotency doesn't promise identical responses or unchanging data. Before automatically retrying POST or a SOAP operation, establish whether the application provides deduplication or another retry-safe contract. Our guide to using third-party APIs covers the integration side.

What Is SOAP?

SOAP is an XML-based messaging framework with defined envelope and processing rules. HTTP is a common binding—a specification of how messages are carried—not a mandatory transport. In SOAP 1.2, “SOAP” is the name, no longer an expanded acronym.

A SOAP message has:

• Envelope: the outer message container.
• Header, optional: blocks carrying metadata or extensions.
• Body: application content, or a SOAP Fault when reporting a SOAP-level failure.

Header processing has defined rules: a node must process a mandatory header targeted at it or generate a fault. That extensibility mechanism isn't itself an authentication or transaction implementation.

WSDL, the Web Services Description Language, describes interfaces, messages, bindings, and endpoints. It's distinct from SOAP: SOAP doesn't require WSDL, and WSDL can describe non-SOAP bindings. Tooling can generate client proxies from WSDL-based metadata.

REST vs SOAP Request and Error Examples

Both examples retrieve order 123 from a hypothetical service. These are illustrative HTTP exchange fragments, not a running service: HTTPS is assumed, while authentication and message-framing headers are omitted. Application payloads and namespaces are examples, not standardized order schemas.

HTTP/JSON Request and Response

GET /orders/123 HTTP/1.1
Host: api.example.test
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private, max-age=60
ETag: "order-123-v7"

{
  "id": "123",
  "status": "paid",
  "links": [
    {"rel": "self", "href": "/orders/123"},
    {"rel": "collection", "href": "/orders"}
  ]
}

The JSON link convention here is application-defined. Including links illustrates navigation; it doesn't prove that the complete system satisfies REST's constraints.

For an unknown order, this API returns an HTTP error with Problem Details, a standardized error representation:

HTTP/1.1 404 Not Found
Content-Type: application/problem+json
Cache-Control: no-store

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "Order 999 was not found."
}

Problem Details is an option, not a REST requirement. The HTTP status communicates the outcome; the response body adds machine-readable and human-readable information.

SOAP 1.2 Request and Response

POST /OrderService HTTP/1.1
Host: api.example.test
Content-Type: application/soap+xml; charset=utf-8; action="urn:example:orders:GetOrder"

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
              xmlns:o="urn:example:orders">
  <env:Header>
    <o:CorrelationId>r-123</o:CorrelationId>
  </env:Header>
  <env:Body>
    <o:GetOrder>
      <o:id>123</o:id>
    </o:GetOrder>
  </env:Body>
</env:Envelope>

The response carries the result inside another envelope:

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
              xmlns:o="urn:example:orders">
  <env:Body>
    <o:GetOrderResponse>
      <o:Order>
        <o:id>123</o:id>
        <o:status>paid</o:status>
      </o:Order>
    </o:GetOrderResponse>
  </env:Body>
</env:Envelope>

HTTP headers sit outside the envelope; SOAP header blocks sit inside it. The example's CorrelationId is custom metadata, not a security feature. The SOAP envelope and HTTP media-type conventions follow the W3C specifications.

SOAP Faults Versus HTTP Errors

This hypothetical SOAP contract models an unknown order as an env:Sender fault:

HTTP/1.1 400 Bad Request
Content-Type: application/soap+xml; charset=utf-8

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
              xmlns:o="urn:example:orders">
  <env:Body>
    <env:Fault>
      <env:Code><env:Value>env:Sender</env:Value></env:Code>
      <env:Reason>
        <env:Text xml:lang="en">Order 999 was not found.</env:Text>
      </env:Reason>
      <env:Detail>
        <o:OrderNotFound><o:id>999</o:id></o:OrderNotFound>
      </env:Detail>
    </env:Fault>
  </env:Body>
</env:Envelope>

SOAP 1.2's HTTP binding maps env:Sender to HTTP 400 and env:Receiver to HTTP 500. The decision to represent “order not found” as a particular application fault belongs to the service contract; don't assume a universal mapping from business errors.

Handle both layers: inspect the HTTP outcome and parse any SOAP Fault. A gateway or authentication failure might return no SOAP envelope at all. Keep transport failures, SOAP processing faults, and contract-defined business outcomes separate in your client error model.

SOAP vs REST: Which Is Right for You?

For the practical comparison below, “REST API” means an HTTP resource API. REST itself isn't a fixed wire format or a synonym for HTTP/JSON.

Neither approach owns contract-first development. OpenAPI supports descriptions and code-generation tooling for HTTP APIs; WSDL-based tooling serves a similar contract role in SOAP integrations. Test the actual generators and language runtimes your consumers use.

Compare Security Requirements, Not Labels

Use TLS and enforce authentication and authorization with either approach. HTTP APIs can use OAuth access tokens; OpenID Connect supplies an authentication layer on top of OAuth. Neither technology is exclusive to REST. See our explanation of how OAuth 2.0 works for the authorization flow.

WS-Security separately defines protection for SOAP message content using tokens, signatures, and encryption. That matters when selected message parts need protection across intermediaries or beyond a single transport connection. It still requires compatible implementations, trust configuration, and correct signature coverage; SOAP alone supplies none of those guarantees.

Make Transaction and Compatibility Requirements Explicit

SOAP does not automatically make operations ACID-transactional. WS-AtomicTransaction defines coordination protocols, including two-phase commit, for participating services. Design either interface around local transactions where possible; if you require cross-service atomicity, verify every participant's support and failure behavior.

For either interface, review changes to required fields, accepted values, null handling, errors, and authentication before deployment. Don't assume an additive field is harmless to every generated client. Run compatibility tests against real consumers rather than treating either “RESTful” or “schema-valid” as a compatibility guarantee.

Choose Against Your Actual Constraints

• Favor an HTTP resource API when shared HTTP semantics, cacheable reads, flexible representations, and straightforward HTTP integration match your consumers.
• Favor SOAP when an existing partner contract requires it, your organization depends on WSDL-generated clients, or a required binding or WS-* capability is implemented and tested across participants.
• Measure rather than assume performance. Compare equivalent operations with production-sized payloads, compression, authentication, parsing, and cache behavior.

One project can expose an HTTP API while calling a SOAP partner behind an adapter. Translate errors deliberately, preserve business semantics, and establish retry rules at that boundary; changing the outer interface doesn't change the downstream contract.

If the deeper question is synchronous calls versus asynchronous work, compare event-driven and REST microservices. For another comparison, see our GraphQL vs REST comparison.

Common Mistakes

• Blind retries: define deduplication and retry behavior before repeating state-changing operations.
• Accidental data exposure through caches: set deliberate cache policies for personalized responses.
• Unprotected XML parsing: follow OWASP's XML parser-hardening guidance, including disabling external entity resolution where applicable.
• Overly detailed errors: return useful error identifiers, not stack traces or secrets.
• Untested interoperability: exercise real clients, authentication failures, Faults, timeouts, and contract changes before release.

These checks complement, rather than replace, HTTP semantics, cache policy, message security, and input validation.

FAQ

What is the main difference between REST and SOAP?

REST is an architectural style that constrains interactions between components. SOAP is an XML-based messaging protocol with defined envelope and processing rules; it doesn't define an entire application architecture.

Is REST always faster than SOAP?

No. Neither label establishes end-to-end performance. Benchmark equivalent workloads and security settings, and account for payload size, parsing, compression, network round trips, and caching.

Is SOAP more secure than REST?

Not inherently. Either approach needs transport protection, authentication, and authorization; WS-Security adds optional message-level protection to SOAP deployments. SOAP also doesn't automatically provide ACID transactions: WS-AtomicTransaction is a separate specification.

Does SOAP require XML and HTTP?

SOAP 1.1 and 1.2 use XML-based envelopes and message structures, but HTTP isn't mandatory. The application payload is carried within that structure; the chosen binding determines how messages are transported.

Can REST and SOAP coexist in one system?

Yes. You can expose an HTTP resource API while integrating SOAP services internally or through an adapter. Define how contracts, authentication, errors, and retries translate across the boundary.

Further Reading

• Fielding's REST architectural style — the original constraints and their trade-offs.
• HTTP Semantics — methods, status codes, safety, and idempotency.
• HTTP Caching — freshness, validation, and cache directives.
• SOAP 1.2 Messaging Framework — envelopes, headers, processing, and Faults.
• SOAP 1.2 Adjuncts — bindings, media types, and HTTP Fault mappings.
• OpenAPI Specification — machine-readable contracts for HTTP APIs.
• WS-Security SOAP Message Security — tokens, signatures, and encryption.
• WS-AtomicTransaction — distributed transaction coordination.