Want to see Parasoft in action? Sign up for our Monthly Demos! See Demos & Events >>
X
Want to see Parasoft in action? Sign up for our Monthly Demos! See Demos & Events >>
Reading Time: 11 minutesThe difference between SOAP vs. REST API. Perhaps you’re already well familiar with SOAP and REST, looking to expand your knowledge or get a new perspective. Or maybe you heard about them and are trying to get a better understanding. After all, SOAP and REST are well established with definitions and specifications going back decades.
Please allow me to describe the SOAP and REST difference, compare, and otherwise shed light on these two significant approaches to web service and web API design. I’ll also highlight some of the testing challenges associated with these approaches and how to solve them. First, let’s define what these are and how they relate to the World Wide Web.
The World Wide Web Consortium (W3C) recommends standards and protocols for the global collection of interconnected resources that we know as the World Wide Web. A “web” resource is accessed at a “web” address and delivered over a “web” protocol.
As someone reading this blog post, you may know that you are reading an HTML document at the URI shown in your browser’s address bar that was requested and delivered using the HTTP(S) protocol. The W3C defined how these same technologies that are enabling you to read this blog post can facilitate communication between software systems. In particular, the W3C defined “web services”, which led to the creation of many other standards and technologies over the years. Let’s take a high-level look at what they are.
| SOAP | Simple Object Access Protocol is an object-oriented protocol whereby objects are exchanged between client and server, serialized to and from XML. The SOAP specification builds build on top of other “web” technologies as defined by the W3C including XML and HTTP. Many specifications are based on or extend the SOAP specification, including some that aren’t so “simple”. A SOAP service exchanges SOAP messages with a SOAP client. A SOAP message is also called an “envelope”. A SOAP envelope has a “Body” element and an optional “Header” element. The “Body” typically wraps or literally “envelopes” another XML document. A SOAP request also indicates the operation or action being invoked. Different operations accept and return different types of documents. |
| REST | Representational State Transfer. Unlike SOAP, REST is not a specific technology but is an architectural style, defining specific constraints for a software system. A REST-compliant web service or web API is often known as a RESTful API or REST API. A REST API’s purpose is for exchanging representations of a resource. A resource can be any kind of entity that can be conceptually identified by a URI. A REST API listens at a base URI with child paths for accessing each of the resources exposed by the API. A resource path may include one or more parameters that can be used to identify a resource, where certain path segments could contain identifiers. Resource parameters may also take the form of query parameters or headers. A REST API exposes one or more CRUD operations to retrieve or manipulate a resource (create, retrieve, update, and delete). |
Now, let’s dig into some details about the difference between soap and rest, understanding how these approaches compare to one another.
A SOAP service defines a set of operations. The operations can be arbitrary in that there are no restrictions in the scope or purpose of the operations being defined. Operations have a signature, typically representative of the fully qualified name of the element inside the envelope’s Body element. For example, the element’s name might be “calculateSomething” or “doSomethingFun”.
A REST API has a collection of operations for each resource. The operation’s that are available are limited to CRUD (create, retrieve, update, and delete). The operations are mapped to HTTP methods like GET, POST, PUT, PATCH, and DELETE.
| SOAP | SOAP operations offer a higher degree of flexibility since they are not limited to CRUD and do not have to be structured around specific resource types like REST. However, operations can also be used for CRUD, where the XML in the SOAP Body can include an XML representation of an object along with its identifier. |
| REST | REST operations offer a higher degree of simplicity. A URI is used to identify the resource, decoupled from the representation of the resource being exchanged. Additionally, operations must be stateless, meaning that the operations behave in a consistent way and not based on the state of the conversation between the client and the service endpoint. |
| SOAP | SOAP services can have much higher complexity by supporting arbitrary operations and by potentially tracking state. An example could be a bookstore service having an “addToCart” operation. Every time a client calls “addToCart”, the service tracks the item in the client’s shopping cart. A different client can call “addToCart” and not impact a different client’s shopping cart. The service tracks the state of each client separately. |
| REST | REST APIs are more restricted than SOAP by having operations limited to CRUD. Additionally, clients have the burden of tracking their own state. In the bookstore example, the client needs to know the ID of its cart so that it can build the correct URI for their shopping cart, like “cart/{id}”. The client could perform a GET at that URI to fetch a structured representation of their cart. The client could also do a PUT at that same URI to update their cart with an updated representation. |
SOAP messaging involves the exchange of XML documents called SOAP envelopes. A SOAP envelope contains a “Body” element and an optional “Header” element. The XML within the “Body” element can be arbitrary but typically represents one or more entities or objects. The content type is either “text/xml” or “application/soap+xml” depending whether SOAP version 1.1 or SOAP version 1.2 is being followed. XML elements in the SOAP can also be used to wrap other types of data, textual or binary. The W3C defined methods called “XOP” and “MTOM” describe how to efficiently package binary data in XML and SOAP messages as a MIME “Multipart/Related”, avoiding the need to base64 encode the binary data directly within XML tags.
REST API messaging involves the exchange of representations of a resource. A “representation” could be any data format. It could be a structured data exchange/interchange format such as XML or JSON, or something completely different like PDF or JPEG. There’s no content-type restriction. A REST API could support multiple data formats or different data formats for different resources.
| SOAP | XML is standardized and well understood, defined by various W3C recommendations. XML has a concept of namespaces, which help disambiguate elements, avoiding naming conflicts. SOAP envelopes provide a layer of encapsulation, enabling the inclusion of additional metadata under the “Header” element. |
| REST | REST APIs aren’t restricted in terms of what data formats they can use. For structured data, use of JSON is common and much faster to consume and produce than XML. However, there are other formats for serializing structured data that can be even more compact and efficient than JSON, like BSON (Binary JSON) or Google’s Protocol Buffers (Protobuf). Any content-type is a possibility. |
| SOAP | XML can also be verbose or bloated compared to other data formats with a relatively high serialization cost to both produce and consume. However, message size can be reduced using compression like the “Content-Encoding: gzip” HTTP compression scheme. Serialization cost can be reduced by using alternative or binary XML encodings, like Microsoft’s .NET Binary Format for XML. |
| REST | There is no standard data interchange format for REST APIs. So, you may need a different set of libraries to consume and produce structured data depending on the REST API you are communicating with. However, JSON is very popular and often available. |
SOAP and REST are extensible but in very different ways. Let’s dive into the comparison.
| SOAP | The protocol binding does not have to be HTTP but could be anything. SOAP Messages could be sent over some other TCP-based protocols like SMTP or could be sent over UDP socket as is done in WS-Discovery and UPnP. Microsoft’s .NET WCF SOAP framework has TCP and named-pipe transports. Event-driven or message-queuing interfaces like JMS (Java Message Service) or AMQP (Advanced Message Queuing Protocol) are also used for SOAP. SOAP also allows for different message exchange patterns. It does not have to be request-reply. It could be asynchronous, one-way or fire-and-forget. SOAP is used in service-oriented architecture (SOA) where services are loosely coupled, pushing, or reacting to messages routed by an enterprise service bus (ESB). |
| REST | REST APIs are extensible in that they can potentially represent resources with different message formats. Unlike SOAP, you aren’t restricted to XML-based representations. New resources can be added without affecting existing resources. REST APIs can be versioned by including some version number or version identifier as part of the URI. |
| SOAP | With higher extensibility comes greater complexity. There’s no single way to implement SOAP messaging, given the various protocols, messaging patterns, and WS-* specifications that may be applied. |
| REST | REST APIs are generally restricted to HTTP, where method and resource URI are sent in the HTTP request header. However, RESTful approaches have been accomplished with other technologies like Constrained Application Protocol (CoAP), which is an implementation of REST for constrained environments for Iot (Internet of things) applications. RESTful principals can also be followed in messaging brokers like RabbitMQ and MQTT, where resource identifier and CRUD operation could be potentially mapped to message destinations or “topics”. |
SOAP was designed with interoperability in mind, following open standards, not bound to any specific implementation or platform or programming language. However, some things in the specification were left open to interpretation. Some parts may be confusing or have errors or typos or bad examples. The issues stem from simple things like whether:
Another standards body, the Web Services Interoperability Organization (WS-I), came about to provide guidelines for web service interoperability. The WS-I provides various interoperability profiles. Each profile has a list of requirements and a list of assertions, which define how to check the requirements. In short, the WS-I profiles say things like “you should do this” and “you shouldn’t do that.” Fun fact: Parasoft was a contributor to the WS-I Basic Profile 1.1 Test Assertions Document (TAD).
REST APIs are interoperable in that they are simple to invoke. There are many tools and APIs that can make HTTP requests. Popular tools include cURL and Postman. Even a simple form on a web page can be used to make HTTP requests. There are also various open standards that are typically used for REST APIs aside from HTTP, including open message formats like JSON. REST APIs can also implement various open standards for security and authorization (more on that later).
| SOAP | SOAP was designed with interoperability in mind. The W3C SOAP specifications are primarily authored by Microsoft, which has their own SOAP stack that’s implemented as part of Microsoft’s .NET Framework, originally .NET Web Service Enhancements (WSE) and later .NET Windows Communication Foundation (WCF). However, SOAP stacks are available from many other vendors including open source projects like the Apache project. Aside from .NET, SOAP stacks are also available for different platforms and programming languages like java, python, and typescript. SOAP clients and SOAP services implemented with different SOAP stacks are capable of communication if they follow the same set of open SOAP standards. |
| REST | REST APIs follow the KISS (“keep it simple, stupid”) principle, following the general design principles of REST software architecture. Being simple to invoke, REST APIs do not necessarily require a complex software stack like you typically need for communicating with SOAP endpoints. |
| SOAP | SOAP has a myriad of extensions often referred to as WS-*. There is WS-Addressing, WS-Policy, WS-Discovery, WS-MetadataExchange, WS-SecureConversation, WS-SecurityPolicy, WS-Trust, WS-Federation. There is also WS-Security with various related specifications including those related to XML and SOAP signature, XML and SOAP encryption, and SAML (Security Assertion Markup Language). The list goes on, and on, and on. Chances are, a SOAP service is going to be following several WS-* specifications, adding complexity to what was originally defined as being a “simple” protocol. Your client has to follow the same WS-* standards as the service, or they won’t be able to communicate correctly. |
| REST | REST APIs do not necessarily have to follow open standards. Although JSON is very popular, there’s no standard data interchange format. Any content-type is a possibility, including possibly proprietary data formats. Additionally, certain security or authorization frameworks can introduce extra complexity, requiring a compatible implementation on the client side. |
Security is an important consideration for both SOAP and REST. Transport layer security is needed to encrypt messages as they’re sent over the wire to prevent eavesdropping. Message layer security is necessary for full end-to-end security, so the message is protected from any intermediaries that may have access to it before reaching its intended destination. Authentication or authorization mechanisms are needed to establish the identity between client and server.
| SOAP | SOAP has a large collection of security specifications known as WS-Security, published by the standards body OASIS. Aside from transport layer security mechanisms like HTTPS, WS-Security specifications describe how to embed security directly within the SOAP messages themselves (including signatures, encrypted data), and how to package security tokens for establishing identity like SAML (Security Assertion Markup Language). |
| REST | REST can leverage existing mechanisms in HTTP for security including SSL and HTTP-based authentication schemes. There are also open standards for authorization including OpenID Connect (OIDC), which builds upon OAuth and some other open specifications like JSON Web Token (JWT). |
| SOAP | OASIS WS-Security specifications are complex. Services implementing multiple WS-Security and other WS-* specifications pose challenges for building clients. What key stores do I need? Do I need to sign the message or encrypt it too? What XML canonicalization algorithm am I supposed to use? Do I need to first get a SAML token and include it in a SOAP Header? What parts of the message do I need to sign and encrypt? |
| REST | Message layer security is not standard, some being proprietary. For example, Amazon AWS provides server-side and client-side mechanisms for encrypting messages sent to or from their APIs. |
There are various types of machine consumable documentation formats for SOAP services and REST. Service definition documents enable automated processing, like automated code generation for clients or service stubs. Service definition documents can also be translated into a human-friendly documentation format like a web page.
| SOAP | SOAP services are described by WSDL, another open specification by the W3C. A WSDL is an XML document. It defines the service endpoints, operations, and XML schemas for request, reply, and fault messages. |
| REST | There are various service definition formats for REST APIs. These include OpenAPI, RAML, API Blueprint, and WADL. They all provide different ways to describe things common to REST APIs like resource paths, parameters, operations, and type and format or schema of representations. OpenAPI is based on JSON Schema specifications and can be represented as either JSON or YAML. RAML documents are based on YAML and support both JSON Schema and XML Schema (XSD). API Blueprint is based on Markdown Syntax for Object Notation (MSON) with support for JSON Schema. WADL is a W3C submission, based on XML with support for describing XML representations using XML Schema, a bit analogous to WSDL for SOAP. |
| SOAP | The WSDL specification has some issues with additional clarification and interoperability recommendations provided by the Web Services Interoperability Organization (WS-I). There are also multiple versions of WSDL. WSDL 1.1 is most commonly implemented. WSDL 2.0, formerly known as WSDL 1.2, was not adopted by all SOAP stacks including Microsoft’s .NET WCF. Interestingly, WSDL 2.0 introduced support for describing REST APIs. |
| REST | There is no standard service definition format for REST APIs. However, OpenAPI is a close consideration for being the standard. OpenAPI was originally developed by SmartBear as “Swagger”, later donated to the Linux Foundation as OpenAPI. The specification is overseen by the OpenAPI Initiative, which includes members from a diverse collection of large corporations including Google, IBM, and Microsoft. |
Each service definition format has its own collection of tooling for code and doc generation. This means you need to use a different set of tooling depending on the service implementation. However, converters exist so you could convert an OpenAPI document to a RAML (or vice versa).
REST and SOAP provide their own unique tradeoffs and challenges, especially with respect to testing. To test an API, you need to be able to build clients, send input data, and then be able to view and validate the output that was returned.
| SOAP | A WSDL document can provide a full description of a SOAP service, including its security requirements. There are various commercial and open source tools available that can consume WSDL documents to automatically produce clients for testing SOAP endpoints. One simple example is Microsoft’s WCF Test Client application. |
| REST | REST APIs can similarly provide a service definition document, which can be consumed to produce test clients. For OpenAPI, Swagger UI provides a simple web interface to “try out” every single operation exposed by the API. |
| SOAP | SOAP services may be implemented using protocols other than HTTP, where communication may require a specific messaging interface like JMS. Various WS-* protocols are complex. Free and open source tools have limitations and lack of support for all transport and WS-* protocols. However, Parasoft SOAtest helps solve this, having comprehensive support for SOAP and related protocols. |
| REST | REST services don’t necessarily have service definitions. Manually building clients can be difficult and tedious, determining the right sequence of API calls to string together to create the desired scenarios. However, Parasoft SOAtest helps solve this. In addition to being able to create test clients from various service definition formats, SOAtest‘s Smart API Test Generator automates API test creation by monitoring API calls and using artificial intelligence to automatically construct and configure test scenarios. |
Is your head spinning yet? Let Parasoft help. Reduce the cost, time, and complexity of testing service interfaces with the full end-to-end API testing solution, Parasoft SOAtest. Whether it be SOAP, REST, or other service interfaces or technologies, SOAtest has you covered. Request a demo today!
Looking beyond SOAP and REST? Check out our Testing Microservices whitepaper to learn more about modern approaches to service-oriented architectures and microservices testing.
Joseph is a Senior Software Engineer at Parasoft. He has helped develop many core features and technologies used in various products including SOAtest, Virtualize, and Selenic. He has been with Parasoft since 2006.