When talking about API (application programming interface) architectures, it’s common to compare SOAP vs. REST, two of the most common API paradigms. Although the two are often compared as apples to apples, they’re inherently different technologies and aren’t easily compared on a granular level.
Why? Because SOAP is a protocol, and REST is an architectural style. A REST API can utilize the SOAP protocol, just like it can use HTTP. So, right off the bat, they’re going to be packaged differently, function, and be used in different scenarios.
Now that we’ve gotten that out of the way, let’s look a little closer at each—including some of the pros that would make you want to use one over the other for your application if the shoe fits.
What is an API?
In the simplest of terms, an API is a piece of software that plugs one application directly into the data and services of another by granting it access to specific parts of a server. APIs let two pieces of software communicate, and they’re the basis for most modern applications. They allow us to streamline IT architectures, automate marketing workflows, and make it easier to share data sets.
What is a rest API?
REST (Representational State Transfer) is truly a “web services” API. REST APIs are based on URIs (Uniform Resource Identifier, of which a URL is a specific type) and the HTTP protocol and use JSON for a data format, which is super browser-compatible. (It could also theoretically use the SOAP protocol, as we mentioned above.) REST APIs can be simple to build and scale, but they can also be massive and complicated—it’s all in how they’re built, added on to, and what they’re designed to do.
Reasons you may want to build an API to be RESTful include resource limitations, fewer security requirements, browser client compatibility, discoverability, data health, and scalability—things that apply to web services.
Some quick REST information:
- REST is all about simplicity, thanks to HTTP protocols.
- REST APIs facilitate client-server communications and architectures. If it’s RESTful, it’s built on this client-server principle, with round trips between the two passing payloads of information.
- REST APIs use a single uniform interface. This simplifies how applications interact with the API by requiring they all interface in the same way, through the same portal. This has advantages and disadvantages; check with your developer to see if this will affect implementation changes down the road.
- REST is optimized for the web. Using JSON as its data format makes it compatible with browsers.
- REST is known for excellent performance and scalability. But, like any technology, it can get bogged down or bog down your app. That’s why languages like GraphQL have come along to address problems even REST can’t solve.
What is SOAP?
SOAP (Simple Object Access Protocol) is its protocol and is a bit more complex by defining more standards than REST—things like security and how messages are sent. These built-in standards do carry a bit more overhead. Still, they can be a deciding factor for organizations that require more comprehensive features in the way of security, transactions, and ACID (Atomicity, Consistency, Isolation, Durability) compliance. For the sake of this comparison, we should point out that many of the reasons why SOAP is a good choice rarely apply to web services scenarios, which makes it more ideal for enterprise-type situations.
Reasons you may want to develop an application with a SOAP API include higher levels of security (e.g., a mobile application interfacing with a bank), messaging apps that need reliable communication, communicating with legacy systems, or ACID compliance.
- SOAP has much tighter security. In addition to SSL support, WS-Security is a built-in standard that gives SOAP some more enterprise-level security features if you require them.
- Successful/retry logic for reliable messaging functionality. REST doesn’t have a standard messaging system and can only address communication failures by retrying. SOAP has successful/retry logic built-in and provides end-to-end reliability even through SOAP intermediaries.
- SOAP has built-in ACID compliance. ACID compliance reduces anomalies and protects the integrity of a database by prescribing how transactions can interact with the database. ACID is more conservative than other data consistency models, which is why it’s typically favored when handling financial or otherwise sensitive transactions.
SOAP vs. REST example
To better grasp the practical differences between SOAP and REST, we have created an example of how the same operation could be performed using the two technologies. In the example, we are requesting user details.
SOAP example
Using SOAP, the request to the API is an HTTP POST request with an XML request body. The request body consists of an envelope which is a type of SOAP wrapper that identifies the requested API, and a SOAP body that holds the request parameters. In this case, we want to fetch the user with the name “John.”
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://www.soapexample.com/xml/users">
<soapenv:Header/>
<soapenv:Body>
<sch:UserDetailsRequest>
<sch:name>John</sch:name>
</sch:UserDetailsRequest>
</soapenv:Body>
</soapenv:Envelope>The response, just like the request, consists of a SOAP envelope and a SOAP body. In this case, the SOAP body represents the requested user data.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>
<ns2:UserDetailsResponse xmlns:ns2="http://www.soapexample.com/xml/users">
<ns2:User>
<ns2:name>John</ns2:name>
<ns2:age>5</ns2:age>
<ns2:address>Greenville</ns2:address>
</ns2:User
</ns2:UserDetailsResponse>
</soapenv:Body>
</soapenv:Envelope>REST example
REST APIs can be called with all of the HTTP verbs. To get a resource, in this case, a user, a GET request is used. While the SOAP request holds the user’s name in the body, a REST API accepts GET parameters from the URI.
GET https://restexample.com/users?name=John
As mentioned, REST APIs typically use the data format JSON. The user is represented in JSON like this:
{
"name": "John",
"age": 5,
"address": "Greenville"
}SOAP vs. REST: The key differences
Below we’ll look at some of the key differences between the two paradigms.
SOAP is a protocol, whereas REST is an architectural style
An API is designed to expose certain aspects of an application’s business logic on a server, and SOAP uses a service interface to do this while REST uses URIs. While SOAP APIs are designed after the functions that the API exposes, REST APIs are designed after the data. For example, a SOAP API that exposes functionality to create a user might include a function called “CreateUser” that would be specified in the SOAP body. A REST API would instead expose a URL /users, and a POST request towards that URL would create a user.
REST APIs access a resource for data (a URI); SOAP APIs perform an operation
REST is an architecture that’s more data-driven, while SOAP is a standardized protocol for transferring structured information that’s more function-driven. REST permits many different data formats, including plain text, HTML, XML, and JSON, which is a great fit for data and yields more browser compatibility; SOAP only uses XML. SOAP APIs are limited to using XML and the format including the SOAP envelope, header, and body, as we saw in the example above. REST APIs are, however, format agnostic. While the most common format is JSON, formats such as XML, plain text, and XML are also valid for REST APIs.
Security is handled differently
SOAP supports WS-Security, which is great at the transport level and a bit more comprehensive than SSL, and ideal for integration with enterprise-level security tools. Both support SSL for end-to-end security and REST can use the secure version of the HTTP protocol, HTTPS. While both SOAP and REST APIs can encrypt their communication using HTTPS and SSL, the additional layer of WS-Security provided by SOAP acts on the message level to make sure not only that the content of a message can be read by the right server but also the right process on the server.
SOAP requires more bandwidth, whereas REST requires fewer resources (depending on the API)
There’s a little more overhead with SOAP out of the gate because of the envelope-style of payload transport. Because REST is used primarily for web services, its being lightweight is an advantage in those scenarios.
As you can see in the example SOAP request in the previous section, a SOAP request contains more data than a REST request. This means more bandwidth will be consumed when communicating with a SOAP API. This can have an impact on systems with large amounts of traffic.
REST calls can be cached, while SOAP-based calls cannot be cached
Data can be marked as cacheable, which means it can be reused by the browser later without initiating another request back to the server. This saves time and resources. Since all SOAP requests are sent using a POST request, and POST requests are considered non-idempotent by the HTTP standard, responses will not be cached at the HTTP level. REST APIs do not have this limitation, but you still need to implement the caching mechanisms yourself if you want to use caching. Caching is a key functionality when performance and scalability come into play.
APIs are built to handle your app’s payload, and REST and SOAP do this differently
A payload is data sent over the internet, and when a payload is “heavy,” it requires more resources. REST tends to use HTTP and JSON, which lighten the payload; SOAP relies more on XML.
SOAP APIs have a very strict communication contract and usually require the client to use a specific client library with generated code to access them. This means SOAP is tightly coupled with the server and provides a lower abstraction layer compared to REST. A higher level of abstraction between two pieces of technology means less control over their interaction. Still, there’s also less complexity, and it’s easier to make updates to one or the other without blowing up the whole relationship. This is a key difference between SOAP and REST to consider. SOAP is very closely coupled with the server, having a strict communication contract with it that makes it more difficult to make changes or updates. A client interacting with a REST API needs no knowledge of the API. Still, a client interacting with a SOAP API needs knowledge about everything it will be using before initiating an interaction.
From a development perspective, a SOAP client usually needs third-party libraries to communicate with a SOAP API. In contrast, the only library you need to communicate with a REST API is normally the HTTP request libraries that come built into your programming language.
SOAP and REST Alternatives
While SOAP and REST have been the primary choices for building APIs during the last decades, other alternatives are becoming increasingly common.
JSON
JSON (JavaScript Object Notation) is an open standard file format used to transmit data objects between many applications. It is a lightweight format to store and transfer data and is often used when sending data from a server to a web page. The simplicity and faster transmission of SOAP make it a viable alternative in many situations.
gRPC
RPC (Remote Procedure Call) is an open-source system developed by Google which uses HTTP/2. It is commonly used to connect services in a microservices architecture and to connect mobile devices to backend services. The advantages of gRPC include more lightweight messages than JSON, high performance, built-in code generation, and support for more connection options such as streaming data.
GraphQL
GraphQL is a query language generally used to load data from a server to a client, but it does so very efficiently. Created by Facebook, this relatively new technology supports reading, writing, and subscribing to changes to data, and GraphQL servers are available for languages like JavaScript, Python, C++, and more.
Just like REST, GraphQL communicates using HTTP and uses the JSON data format. One of the key differences and benefits is the possibility to specify the data you want to be returned from the server in one API call. For example, if we want to fetch a customer, the customer orders, and the orders shipment status using REST, we would have to conduct separate HTTP requests for each piece of data. With GraphQL, we can fetch everything using one request, which eliminates the HTTP overhead for each call.
Which API should you choose for your project?
For the most part, when it comes to APIs for web services, developers tend toward a RESTful architecture unless the SOAP path is a better choice, say for an enterprise app that’s backed by more resources, needs super-tight security, and has more requirements.
Additional advantages in choosing the REST API include:
- Lightweight communication using HTTP and small payloads, for example, in the JSON data format
- Fewer requirements for external libraries on the client-side
- Enables the use of effective caching
There are, however, cases when SOAP might be your first choice, including:
- Enterprise-level requirements on security
- Need to integrate with legacy systems already using SOAP
- Requirements on ACID transactions or the use of the built-in retry mechanisms SOAP provides
No matter which technology you use, the most important part of building a good API is designing it using best practices to make it easy to use and understand for clients. A well-designed API can greatly increase your delivery speed and future-proof your technology stack.
