SOAP versus REST
Introduction
For years there has been a war raging between those who advocate the use of SOAP for web services versus those who advocate using REST. There has been a lot of misinformation. This paper presents the facts you need to make your own decision.
First, a quick review of SOAP and REST.
SOAP
SOAP is a way of exchanging messages on a network, such as the Internet. SOAP provides a set of XML elements and attributes—an XML vocabulary—that you use to construct your message. The structure of a SOAP document is: "big picture" data in a SOAP <Header> element, "detail" data in a SOAP <Body> element, and a SOAP <Envelope> element that wraps both. People commonly refer to this structure as the "SOAP message framework."
SOAP messages are exchanged between "SOAP nodes."
Between the sender of a SOAP message and the ultimate recipient there may be intermediary SOAP nodes. The intermediary nodes may only process the elements in the header section. Only the ultimate recipient may process the body. How SOAP messages get routed to intermediaries is outside the scope of SOAP.
SOAP has a processing model. To conform to the SOAP specification, a SOAP node must operate in a certain way. Each SOAP element and attribute has a well-defined meaning and behavior; SOAP nodes must process the SOAP XML vocabulary accordingly. Thus, SOAP is referred to as a "protocol."
Here is the SOAP processing model in a nutshell: Each XML element in the header section may be targeted to a specific intermediary by attaching a SOAP role attribute. An intermediary may add to, remove, or modify some of the XML elements in the header. The intermediary can be required to process an element by adding a SOAP mustUnderstand attribute. An intermediary that receives a SOAP message but does not understand an element in the header section that it is expected to understand, must respond to the sender with a SOAP message that contains a description of the problem. Included in the SOAP XML vocabulary are several "fault" elements that are used to describe the problem. After an intermediary processes an XML element in the header, the intermediary may delete the element. The sender of the SOAP message may desire a header element be carried along all the way to the ultimate recipient. A SOAP relay attribute can be added to a header element to inform the intermediary not to delete it.
A large part of the SOAP specification deals with specifying the behavior of SOAP intermediaries. If there are no intermediaries—which is generally the case—then the SOAP processing model is simply this: validate that the <Envelope>, <Header>, and <Body> elements are in the SOAP namespace and then forward the document to the appropriate domain-specific application (the application that will actually process the data).
SOAP uses HTTP. Before a SOAP message is sent, an HTTP message is created, the URL of the destination SOAP node is placed in the HTTP header and the SOAP message is then placed inside the HTTP body. Note that the SOAP message is placed within an HTTP message. Thus, there is a message within a message. HTTP is a message protocol. SOAP is a message protocol. Thus, there is a message protocol within a message protocol.
A SOAP message doesn't have to be placed within an HTTP message, but it is the most popular way to exchanging SOAP messages. It is commonly referred to as "SOAP over HTTP."
REST
REST is also a way of doing things on a network. With REST each item on the network is identified by a URL. The items are called "resources." Thus, each resource is identified by a URL. To fetch a resource, simply enter the URL. This is known as "dereferencing the URL". The fetched value will be a representation of the resource. If you fetched the resource using a browser then the representation will likely be an HTML document; if your software application did the fetching then the representation may be an XML document. Each type of representation is called a MIME type. HTML and XML are two MIME types. There are over 350 different MIME types (SOAP is one of the MIME types). When you fetch a resource—dereference its URL—you may specify what MIME type you would like to receive.
You can also update resources. For example, when you use your browser to fill in an online form and press the Submit button, the data you entered is sent to the resource, which is updated with your data. If it is a software application that is used to send the updates, it may send them in the form of XML documents.
The format of the data that is returned from a fetch or the data that is sent in an update is up to you. REST doesn't prescribe what format—MIME type—to use.
There are only two parties involved in a RESTful exchange; thus, it's a point-to-point exchange of information.
REST uses HTTP. Before fetching a resource, an HTTP message is created; the URL to the resource is inserted into the HTTP header and the HTTP message is sent to the resource; there is no HTTP body. When you update a resource, an HTTP message is created; the URL of the resource is inserted into the HTTP header and the HTTP body contains the data. The HTTP headers have a well-defined meaning. Resources process the headers according to their meaning. Thus, HTTP is a "protocol."
Since REST doesn't specify a particular XML vocabulary, it has no processing model in the sense of the SOAP processing model; how a REST resource processes update data is up to the resource. Likewise, how a resource processes a fetch request is not prescribed. REST resources conform to the HTTP protocol, which is a processing model.
Recap
REST is a way of interacting with resources on a network. Each resource is identified by a URL. To fetch a resource, derereference its URL. You can also update resources by dereferencing the resource and sending it data. REST doesn't prescribe the format—MIME type—of data exchanges.
SOAP versus REST
SOAP is about exchanging messages between SOAP nodes. REST is about getting information from resources and updating resources with information.
SOAP provides a skeletal XML vocabulary—a framework—that you use to construct your messages. REST does not provide an XML vocabulary; when you want to update a resource, the data can be in any format that's appropriate. So, SOAP is exclusively XML-based, whereas REST information exchanges can potentially be in any of the 350+ MIME types.
SOAP is a protocol—the SOAP specification prescribes how SOAP processors must behave upon receiving a SOAP message. Since there is no REST XML vocabulary, REST does not prescribe how resources should process the information received.
A SOAP message is typically embedded inside an HTTP message. Thus, a SOAP node must conform to the rules of HTTP as well as the rules of the SOAP specification. REST information exchanges also use HTTP. Thus, a REST resource must conform to the rules of HTTP.
A non-SOAP XML document can contain the same data as a SOAP document.
Example
An FBI agent spots a terrorist in Boston. Using his wireless netbook he enters data into an application and presses its Submit button. Using the data entered by the agent, the application constructs and transmits the following SOAP document to the national Persons of Interest web service:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
<soap:Header> <!-- Big Picture Data -->
<code>3810</code>
<location>
<city>Boston</city>
<state>MA</state>
</location>
<urgency>A1A</urgency>
</soap:Header>
<soap:Body> <!-- Detailed Data -->
<code>3810</code>
<field-agent>********************</field-agent>
<datetime>2010-04-21T15:37:00</datetime>
<description>Terrorist spotted - Abdhul Bengandetti </description>
<physical-characteristics>
<sex>male</sex>
<height>6"</height>
<weight>180 pounds</weight>
<hair-color>black</hair-color>
<facial-hair>
<mustache />
<beard />
</facial-hair>
</physical-characteristics>
<clothing>Traditional Arab ankle-length jillaba</clothing>
<location>
<steet-address>202 Boylston Ave.</street-address>
<city>Boston</city>
<state>MA</state>
</location>
</soap:Body>
</soap:Envelope>
Alternatively, the application may construct and transmit the following non-SOAP XML document to the national Persons of Interest web service. Note that it contains the same data as the SOAP document, but doesn't use the SOAP elements and attributes; rather, it exclusively uses domain-specific elements and attributes:
<person-of-interest>
<header> <!-- Big Picture Data -->
<code>3810</code>
<location>
<city>Boston</city>
<state>MA</state>
</location>
<urgency>A1A</urgency>
</header>
<body> <!-- Detailed Data -->
<code>3810</code>
<field-agent>********************</field-agent>
<datetime>2010-04-21T15:37:00</datetime>
<description>Terrorist spotted - Abdhul Bengandetti </description>
<physical-characteristics>
<sex>male</sex>
<height>6"</height>
<weight>180 pounds</weight>
<hair-color>black</hair-color>
<facial-hair>
<mustache />
<beard />
</facial-hair>
</physical-characteristics>
<clothing>Traditional Arab ankle-length jillaba</clothing>
<location>
<steet-address>202 Boylston Ave.</street-address>
<city>Boston</city>
<state>MA</state>
</location>
</body>
</person-of-interest>
With both versions the message is processed by the national Persons of Interest web service. The web service inspects the "big picture" data in the header section and then routes it to appropriate agencies—Boston Police department, the Massachusetts State Troopers, NSA, CIA, and FBI. Only the Federal agencies are authorized to see the name of the field agent, so the data in the <field-agent> element is encrypted. This encryption is done in both the SOAP version and the non-SOAP version, and is represented by ****************.
As far as the FBI agent is concerned, Persons of Interest web service is the ultimate recipient. The fact that the web service forwards the message to other web services is transparent to the agent. The Persons of Interest web service is not an intermediary. Rather, there is a sequence of point-to-point exchanges: FBI agent to Persons of Interest, Persons of Interest to Boston Police, Persons of Interest to Massachusetts State Troopers, and so forth.
Consider the Boston Police web service. For it to process the above SOAP version it must be a SOAP node—it must have installed a SOAP-compliant processor. The SOAP processor checks that the message conforms to the SOAP specification: it validates that the Envelope, Header, and Body elements belong to the SOAP namespace. The SOAP processor then hands off the document to a domain-specific application, a terrorist-sighted application. This is where the real processing occurs.
The whole point of any message or information exchange is to get the message/information into the "hands" of the entity (application) that needs it and will process it. With SOAP an extra step is incurred—a SOAP message is processed by a SOAP processor first and then the message is handed off to the entity/application that actually processes it. With REST the information is delivered directly to the entity/application for processing. Thus, an issue to consider is: does the cost of the SOAP processor and the delay it introduces justify its use? What value-add does it provide?
Recap
With the non-SOAP version (i.e., the REST version), the domain-specific application—the terrorist-sighted application—directly receives and immediately processes the message.
With SOAP the message gets to the application only after a SOAP processor has processed it.
Message Security
Security is frequently (mis)cited as a distinguisher between SOAP and REST. This section gives you the facts.
In the above Persons of Interest example the value of <field-agent> is encrypted to ensure that only certain recipients can view its value. XML Encryption is a technology that can be used to encrypt XML documents (the whole document or just pieces of it). XML Encryption may be applied to both SOAP documents and non-SOAP XML documents.
HTTP has a built-in encryption mechanism so oftentimes it is not necessary to use XML Encryption. Whenever you make a purchase on the Internet, your transaction is secure because the data exchanges are encrypted. You may notice the URL begins with https://..., which indicates that secure HTTP (https) is being used. Browsers show a padlock on the bottom, right corner of the window to indicate that your purchase is being conducted in a secure fashion. Although HTTP already provides built-in encryption and it is often sufficient, there is nothing to prevent you from also using XML Encryption or even using XML Encryption instead of secure HTTP.
XML Digital Signature is a technology that is becoming increasingly popular as a means to ensure that XML messages are not altered in transit (this is known as ensuring the "integrity" of the message). This technology may also be used with SOAP documents and non-SOAP XML documents. HTTP has a built-in integrity mechanism so oftentimes it is not necessary to use XML Digital Signature. Although HTTP already provides built-in integrity and it is often sufficient, there is nothing to prevent you from also using XML Digital Signature or even using XML Digital Signature instead of the integrity mechanisms provided by HTTP.
For many web services the security built into HTTP is sufficient.
The WS-* technologies—XML Encryption, Digital Signature, and others—are being developed for XML documents. A SOAP document is an XML document so the WS-* technologies may be used with SOAP documents. They may also be used with non-SOAP XML documents. For example, the above Persons of Interest example showed XML-Encryption applied to the <field-agent> element in both the SOAP version and the non-SOAP version.
There is considerable discussion among web service developers about the complexity of the WS-* technologies. Some argue they are too heavy weight and lighter weight alternative technologies should be used instead. While this is a useful debate it is not relevant to the SOAP versus REST debate. The point to be made plain with the SOAP versus REST debate is that the WS-* technologies may be used with both SOAP documents and non-SOAP XML documents.
Recap
With respect to message security, there is nothing that can be done with SOAP documents that can't also be done with non-SOAP XML documents.
Summary
SOAP is an XML vocabulary, intended for use with web services. A SOAP processor is an application that processes SOAP elements and attributes according to the SOAP specification, and then hands the document over to a domain-specific application. With REST, the entire message is domain-specific, and the XML document is immediately processed by the domain-specific application. Thus, with SOAP there is some pre-processing before arriving at the domain-specific application. With REST the data arrives immediately at the domain-specific application.
Security is commonly (mis)cited as a distinguishing feature between SOAP and REST. This document explains why that is unfounded. Any XML security technology—XML Encryption, XML Digital Signature, and others—that can be applied to a SOAP document can also be applied to a non-SOAP XML document.
Translation: This article has been translated to Swedish by Daniela Milton: http://www.autoteilexxl.de/edu/?p=2186
Last Updated: March 11, 2015