SOAP vs REST: Differences, Use Cases and the Same Request in Both

What is the difference between SOAP and REST?

SOAP is a protocol for exchanging messages. REST is an architectural style. That one sentence explains most of what follows.

A SOAP message always has the same frame, an XML envelope that holds an optional header and a body. The frame is defined by the protocol, so every SOAP service speaks the same outer language no matter what it offers. REST prescribes no such frame. A REST design takes the structure HTTP already provides, with an address for each resource, a method for the action and a status code for the result, and leaves the body to a media type of the designer’s choice.

Errors show the split clearly. A SOAP service reports a failure as a Fault element inside the body, and the HTTP binding adds a status code to the response. A REST service reports it through the status code, and a body with details is optional. The comparison table further down puts the remaining differences in one place.

A second difference sits in how a request says what it wants. In SOAP the operation is named inside the message, by the element in the body, so the same HTTP address can serve many operations. In REST the operation is expressed by the method applied to an address, so the address changes from resource to resource and the method does the rest.

What is SOAP?

The SOAP Version 1.2 specification calls SOAP “a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment” and defines “an extensible messaging framework” using XML technologies. Part 1 of the second edition is a W3C Recommendation dated 27 April 2007, which is the sense in which SOAP 1.2 counts as a W3C standard.

The envelope is the outer element. Inside it sit an optional Header, which carries information about the message, and a required Body, which carries the content. When something goes wrong, the Body holds a single Fault element, and that Fault is the only child of the Body. These parts make four building blocks in all: Envelope, Header, Body and Fault, with the Header optional.

SOAP separates the message from the transport. A message can be bound to different protocols, and the specification mentions carrying it in an HTTP entity body or over a TCP stream. On the web, HTTP is the usual choice. Because the messages are XML, their content can be described with XML Schema, and for the choice between XML and other formats, XML vs JSON sets out the trade-offs.

SOAP 1.1, published in May 2000, is only a W3C Note and not a Recommendation, so the description of SOAP as a W3C standard applies to version 1.2 only. Services are commonly described in WSDL. WSDL 2.0, a W3C Recommendation from 26 June 2007, is an XML language for describing web services. The older WSDL 1.1 is only a W3C Note from March 2001. Only web services are meant here; the word SOAP has other everyday meanings that have nothing to do with messaging.

What is REST?

REST is an architectural style with constraints, set out by Roy Fielding in his dissertation. In chapter 5 he says the style ignores “the details of component implementation and protocol syntax”, which is why it asks for no message frame of its own. What it does require is a uniform interface, and that includes self-descriptive messages: each response says how it is to be read.

In practice that means resources and representations. A resource is the thing behind an address, such as order 42. A representation is its state in a format such as JSON or XML. RFC 9110 states that HTTP vests the request semantics in the request method, so the method says what is wanted and the status code says what happened. A client of a REST service needs to know three things: the address of the resource, the method that expresses its intent and the media type it expects back. The full picture, with the constraints one by one, is on the page about REST web services, which answers what a REST API is in detail.

SOAP vs REST: the same request in both formats

The task is to read order 42. The two requests at the top of the page do that. The SOAP side builds an envelope in the SOAP 1.2 namespace, puts an application element called GetOrder in the body and names the order in a child element. The REST side is a GET to the address of the order. The envelope was checked against the W3C schema for SOAP 1.2 envelopes.

A successful answer looks like this in each style:

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Body>
    <o:GetOrderResponse xmlns:o="https://example.com/orders">
      <o:id>42</o:id>
      <o:status>shipped</o:status>
    </o:GetOrderResponse>
  </env:Body>
</env:Envelope>

HTTP/1.1 200 OK
Content-Type: application/json

{"id":42,"status":"shipped"}

The SOAP response is 254 characters. The JSON body of the REST response is 28. The numbers belong to these two examples and say nothing about services in general.

The failure case is where the styles part ways. If order 42 does not exist, the SOAP service answers with a Fault:

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Body>
    <env:Fault>
      <env:Code>
        <env:Value>env:Sender</env:Value>
      </env:Code>
      <env:Reason>
        <env:Text xml:lang="en">Order 42 not found</env:Text>
      </env:Reason>
    </env:Fault>
  </env:Body>
</env:Envelope>

Each part has a job. The Code says who is at fault, here the sender of the request. The Reason carries text for a human reader, tagged with its language. Because the Fault is the only child of the Body, a client can tell a failure from a result by looking at a single element.

This Fault is 320 characters. In the HTTP binding of SOAP 1.2, a Fault with the code Sender is sent with status 400. The REST service answers the same request with 404 Not Found, and the body is optional. Where the choice of method matters, as it does in REST once an order is created or changed, PUT vs POST covers the rules.

SOAP API vs REST API: comparison table

Should I use SOAP or REST?

Four questions lead to a decision. The answer that follows is an editorial recommendation, not a statement from a standard.

1. Does a partner or an existing system prescribe a SOAP and WSDL contract? Then use SOAP. Replacing a contract the other side has fixed is not a design decision you can make alone.
2. Is a machine-readable contract in WSDL a requirement of the project? SOAP services are commonly described in WSDL. For REST, a description such as OpenAPI has to be added deliberately.
3. Will browsers, mobile apps or scripts call the interface directly? REST fits, because a call is an HTTP request any client can make without building an envelope.
4. Do you need to add information about a message that is separate from its content? SOAP has a header element for that, and REST uses HTTP header fields.

Short version: for a new interface over HTTP without a prescribed contract, choose REST. Choose SOAP when question one or two answers yes.

Is SOAP safer than REST?

Nothing in the standards says one style is safer than the other. OWASP has a REST Security Cheat Sheet, whose topics include HTTPS, access control, JWT, API keys, input validation and error handling, and a separate Web Service Security Cheat Sheet for SOAP services, which lists transport confidentiality, message integrity and schema validation among others. Both are lists of measures. Neither document compares the two styles. Editorial view: protection comes from the measures a service puts in place, and the label SOAP or REST does not supply any of them. A service that skips HTTPS, access control or input validation is exposed in either style.

Are SOAP APIs outdated, and how do I move from SOAP to REST?

Whether SOAP is still used is a question about numbers, and an honest answer needs a source with numbers. What a project can decide without them is whether a partner contract or an existing system requires SOAP. If neither does, a move to REST is a design choice, and it follows three steps. The order service from above serves as the example.

1. Cut the operations into resources. The operation GetOrder becomes a GET on /orders/42, and a CreateOrder operation becomes a POST to /orders.
2. Map each Fault to a status code. The Sender fault for a missing order becomes 404 Not Found, and a malformed request becomes a 400-class response.
3. Replace the WSDL contract with a description of the HTTP interface, for instance an OpenAPI document, and publish the new resources before the old operations are switched off.

Clients have to change as well. A partner who built against the envelope has to rewrite every call, so one way to avoid forcing a date on them is to run both interfaces side by side for a period.