This is a primer on SOAP and REST

I’ve written it in an interleaved style so that you can compare and contrast these competing technologies for yourself. Using the best tool for the job has been a consistent theme of this blog from my second post. I’ve tried to be as objective as I can. I’ve used both SOAP and REST. They both are good tools. I like the automation and compositional extensibility that comes with SOAP, and the simplicity and layering that comes with REST, and would love to see all these features in one nice “standard” package.


SOAP stands for Simple Object Access Protocol. This is intended to be a lightweight protocol to access objects over distributed networks such as the Internet. SOAP operates by transferring messages from a sender to a receiver, possibly through one or more SOAP intermediaries. An intermediary is a both a receiver and sender of a message. It acts much like a router or switch in a network in that it receives a message and forwards it along to its final destination, possible providing additional services at the same time. Senders, receivers and intermediaries are different types of nodes in the path that a message takes. SOAP nodes can be communicated with via Internet protocols such as HTTP or SMTP. The mechanism by which this communication is established is defined by binding the SOAP end point address to a protocol. HTTP is the most commonly discussed protocol that can be used with SOAP.

REST stands for REpresentational State Transfer. This is intended to be a lightweight way to access resources over distributed networks such as the Internet. The intermediaries of REST are the existing intermediaries of the Internet that use those protocols, including gateways and caches. While intermediaries can provide additional services along the way, those services are typically the existing set of services that these intermediaries provide to users of those existing protocols. RESTful services can be defined in terms of existing Internet protocols such as FTP, HTTP and SMTP.

SOAP messages define an operation on an object. The message body and operation name provide the signature of the message. This signature is used to identify the method to be performed on the object being accessed. Thus, SOAP can define any number of methods on an object.

A REST message is communicated using existing operations defined in the Internet protocols that it is transmitted over. HTTP is the most commonly discussed protocol with respect to REST. The PUT, GET, POST and DELETE operations of the HTTP support the creation, retrieval, update and deletion of resources. These are the four basic functions on persistent storage, commonly (and not always pejoratively) referred to as CRUD.

The messages in the SOAP protocol have two components: The optional message header contains information that may be used or updated by intermediaries along the message path. The body of the message is intended for the final SOAP receiver in the message path. The header and the body appear in the SOAP envelope. All of the content in SOAP is expressed in an XML document starting with the SOAP envelope. The header can be used to control the kind of processing that SOAP intermediaries perform along the path to the receiver. Blobs can be communicated by attaching them to the SOAP message and identifying them in the XML content of the message body.

The messages in REST are blobs that are represented in any MIME type that can be communicated over the existing Internet protocols. RESTful services using HTTP often use XML or JSON as the message content being communicated, but this is not a requirement of a RESTful service.

The messages in SOAP describe operations being performed on an object (resource). These operations can change the state of the object. Most often, SOAP senders and receivers represent the two end-points in a client-server relationship, where the server maintains the state of the object being accessed by the client. Operations can be thought of as the methods of the object, and SOAP as a mechanism to call these object methods remotely. Thus, SOAP most often resembles a “remote procedure call” on an object. The operation being performed on the object is identified in the SOAP message exchange in the MIME and/or SOAP header communicated during the exchange. The SOAP body helps to identify the “method signature” so that the right procedure is called on the server based upon the message inputs. The same service endpoint may be used to perform different operations. Service endpoints are Internet addresses (URLs).

The messages in REST result in the transfer of the state of a resource (object) from the server to the client. At the conclusion of the exchange the resource (object) is “at rest”. Resources are identified by Internet addresses (URLs). The server is not required to maintain the state of an object across service calls.

SOAP requires specialized intermediaries to provide additional services, and the kinds of additional services being provided are limited only to the creativity of developers providing those intermediaries. REST does not require specialized intermediaries, but the kinds of additional services provided to a RESTful client are often limited by services already offered along the communications path between the client and the server (e.g., caching, routing or gateways).

The existence of the SOAP header has allowed the development of specialized profiles of the SOAP standard to define specific header elements that support specific services such as addressing and routing, access control, authentication, message encryption, reliable messaging, et cetera. Thus, the SOAP header allows for new services to be created by composition of intermediaries and receivers. For example: A header element containing a SAML assertion appearing in a SOAP message can be used to communicate user identity information. An intermediary service can perform appropriate authentication and access control checks before passing the operation on to its final destination, logging the result.

Similar capabilities can also be provided through REST, but there is no defined mechanism in REST to enhance a service by composition through intermediaries. In fact, the whole notion that an intermediary is present is hidden from the end user of a RESTful service. Other services can implement their capabilities by using the services of other RESTful services. For example, the Twitter message that many received notifying them of this post was generated by a server that drew on the capabilities of two RESTful services (the Atom feed from this blog, and the RESTful interface of Twitter).

SOAP and REST operate at two different layers of the network stack. SOAP tells you how a message is wrapped and can be extended. REST says nothing about the message, but talks about how the resource is identified and communicated with.

SOAP is a Standard. RESTful is more like a philosophy. They both provide a remarkably similar set of capabilities.

Coming Soon: WSDL and WADL

P.S.  Thanks to Brian Ahier for the topic Suggestion