REST vs. SOAP: What is the difference?

An API is an abbreviation for?Application Programming Interface. APIs specify how different software components should interact and communicate programmatically.

A common type of API is a Web API. Web applications (including websites) send requests to Web APIs, or web services, to request data to display to the user. Think about a website that takes your search criteria and returns the “best deals” on flights, hotels, or car rentals. This website does not retrieve this data from its database. Instead, it retrieves data by sending requests to APIs specializing in flights, hotels, etc. A “Web” API is an API that transmits data using the HTTP protocol.

The two most popular specifications for Web APIs are?REST?and?SOAP.

There is debate about which architectural style is the best to build an API around. They are both specifications, but you cannot compare them “apples to apples”. The subtle distinction is REST is an API architectural style while SOAP is a protocol for accessing web services. While they may seem to compete, both have separate use cases.

This article will explore the differences between these two standards and when to use one over the other.

REST and SOAP: Similarities and Differences

So, what is the commonality between REST and SOAP, and why are they so frequently compared? REST and SOAP are specifications that provide standards for how clients access and interact with web services and the functionality they expose. As mentioned before, REST is an API architectural style, and SOAP is a protocol for data transmission.

REST, as an architectural style, places certain constraints on the design of a web API. The REST standards require web APIs considered “RESTful” to adhere to REST constraints. These constraints include separating the client from the API server, statelessness, and cacheability, to name a few.

SOAP, as a web API protocol, is a standard for data transmission that dictates how messages are 1) structured (the format), 2) sent (the communication protocol), and 3) processed (processing model). Unlike SOAP, REST does not specify how to process messages.

Since SOAP is just a web API protocol, a REST API can use SOAP protocol as its standard for data transmission. However, REST and SOAP are different standards and generally are not mixed.

While one is an architecture and the other a protocol, both provide standards for API message formats. REST and SOAP’s message formats are human and machine-readable. For REST, JSON is a lightweight data interchange format that is highly browser-compatible. For SOAP, XML is an extensible markup language that allows for custom descriptive tags for easy readability. These data formats are discussed in more detail later.

SOAP before REST

SOAP came before REST. REST’s design was meant to address some of SOAP’s issues. The goal of REST was to be lightweight, highly browser compatible, separate the client from the server, and provide the ability to implement caching.

So, if REST came after SOAP, and REST addresses SOAP’s issues, why is SOAP still around?

While REST has clear advantages over SOAP, and in some ways, was meant to replace SOAP, SOAP has its use cases. For example, SOAP is suited for enterprise-level applications that require message-level security.

What is a REST API?

REST stands for Representational State Transfer ?and is a particular architectural style by which APIs considered “RESTful” are constrained. RESTful APIs are required to have a 1) uniform interface, 2) be stateless, 3) are cacheable, 4) separate the client from the server, 5) are a layered system, and 6) are “code on demand”. REST APIs are web APIs that use HTTP protocol where a client sends an HTTP request for data to an API Server, and then the server sends an HTTP response with encoded data back to the client.

Clients access and manipulate data exposed by REST APIs using “resources”. Resources represent different API functionality, and they are accessed using resource URLs. Think of a resource as a data object returned by the API. When sending a request, you pass a method corresponding to a CRUD (Create, Read, Update and Delete) operation to the resource. Consider methods as “actions” taken upon a resource, like creating, updating, or deleting a resource.

For example, the well-known?Swagger Petstore API ?consists of several resources. These resources include Pet, Store, and User. All relate to the central theme of a pet store, but each represents the different data objects you can create, manipulate, or delete.

To request a resource, you send an HTTP request to that resource’s unique URL, specifying the action (method) to take upon the resource. Example actions include creating, updating, retrieving, or deleting a resource (POST, PUT, GET, and DEL, respectively.)

Advantages of REST API

Client-Server Separation

The separation of the client from the server components has the following benefits:

Portability for all components.?Since the user interface is separated from the server, it is portable to many platforms. The server components have portability because REST architecture is “multi-layered”. REST APIs are adaptable across platforms which allows for easy testing during development.

Increases scalability?by restricting the interaction of architectural layers (multi-layered architecture). This restriction simplifies server components. This architecture also increases flexibility to migrate data between servers and roll out new changes quickly.

Easier integration. REST allows developers to focus more on the user interface, functionality, and business rules rather than the server components and data management handled by the API Server.

Supports JSON Message Format

REST’s use of JSON as a data format has several advantages:

• Browser Compatibility?– JSON as a data format is very browser compatible and is friendlier to browsers.
• Uses Less Bandwidth?– JSON is an extremely lightweight and easily parseable data format. XML payloads (in the case of SOAP) are larger than JSON. Larger payloads require more bandwidth. The amount of code writing necessary to compose an XML SOAP request contributes to message size.

Message Format Flexibility

In addition to JSON, REST offers more message formats like HTML, plain text, XML, YAML, and more. The flexibility of message formats makes REST particularly beneficial for?public APIs .

What is SOAP?

SOAP is an acronym standing for Service Object Access Protocol (SOAP). According to SmartBear, it is a “standards-based web services access protocol”. In other words, it is a protocol for how clients and API servers transmit data back and forth. The primary aim of SOAP is the following:

• SOAP uses a structured and extendible message format – XML
• SOAP uses a variety of communication protocols – HTTP, SMTP, TCP, etc.
• SOAP is independent of the implementation language of the web API.

SOAP uses XML as its data format. XML stands for Extensible Markup Language. According to Mozilla:

“XML is a markup language similar to HTML, but without predefined tags to use. Instead, you define your tags designed specifically for your needs.”

XML allows you to store and share information using self-descriptive tags rather than predefined tags like HTML. XML is standardized and so is highly transportable across platforms and systems. XML as a message format is very customizable. You can define XML schemas that validate the structure of XML payloads to ensure they are compliant.

Clients access and manipulate data exposed by SOAP APIs differently than REST APIs. REST allows clients to access “data” using resource URLs. SOAP, on the other hand, involves accessing API “functions” that manipulate data.

Unlike REST, no methods (CRUD operations) are part of a request. Instead, separate functions handle CRUD operations on the same data object. For example, a REST API may have one endpoint (URL) for creating or updating a resource by passing a POST or PUT method in the request. Creating or updating a data object using SOAP would require sending requests for creating or updating to separate functions that handle those specific CRUD operations.

The primary way XML messages are transmitted is using HTTP or HTTPS protocol. However, SOAP APIs can send data using transmission control protocol (TCP), simple mail transport protocol (SMTP), and user data protocol (UDP). REST, on the other hand, only supports HTTP protocol.

Advantages of SOAP

More secure

SOAP is well-suited to security-critical web services because it uses WS-Security (along with SSL) and built-in ACID compliance. REST has neither of these features. WS-Security is a specification for how SOAP XML messages are signed and encrypted. The Header block of every SOAP request contains the security information necessary to complete the request. ACID Compliance is a set of standards for protecting the integrity of a database. Many enterprise-level and financial transaction applications require ACID Compliance.

Flexible Transmission Channel

SOAP supports several communication protocols. REST only supports HTTP. With SOAP, you can use HTTP, HTTPS, user data protocol (UDP), transmission control protocol (TCP), or simple mail transport protocol (SMTP).

Anatomy of REST Message

A REST message has the following components:

• Method?– The CRUD operation to wish to perform against a resource. In this case, the HTTP method POST indicates the desire to create something.
• Endpoint?– The specific endpoint to a resource (resource URL). In this case, the endpoint is https://petstore.swagger.io/v2/pet. A resource is a data object returned by the API that can be targeted using endpoints.
• Header?– Specifies the format of the message, in this case, JSON. You pass authorization tenants like API keys in the headers of requests.
• Request Body?– Contains a JSON object containing properties to attribute to the new resource. In this case, the Request Body includes details for the new pet. Request bodies are similar to parameters, except they are objects containing multiple properties instead of one.

Below is a REST API cURL request to the Swagger Petstore API that creates a pet.

Anatomy of SOAP Message

A SOAP XML message has the following “blocks”:

• Envelope?– Required block that identifies the XML message as a SOAP message (different from other XML messages). The namespace attribute points to the latest version of SOAP.
• Header?– Optional block that stores authorization properties, like API keys, etc.
• Body?– Required block that specifies what information you expect to receive back from the API after the request is submitted. This block includes the function name (procedure) and parameters you wish to pass that will affect the result. In the response, the Body block contains the response of the API with the requested information.
• Fault?– Optional block. If a SOAP API cannot process the request, it will send a fault message defined here. There are many reasons why a request can fail. For example, the message structure may be invalid according to the XML schema definition.

To understand the structure of SOAP, let us compare a REST message to a SOAP message. Below is a REST API cURL request to the Swagger Petstore API that retrieves a pet based on a petId. The petId 1 is a path parameter included at the end of the resource URL of the request.

Below is the SOAP equivalent of the same request to show the differences.

The following are some differences:

• Message format:
• REST – cURL is the language used to compose the HTTP request. However, you can send REST requests in any number of languages. The message payload (message body) is JSON.
• SOAP – The message format is XML. The XML structure is enforced by an XML schema.
• Methods (CRUD operations):
• REST – The GET method is provided with the request that tells the API to retrieve something.
• SOAP – No method is provided with the request. The request is sent to a procedure that deals with retrieval (GetPet function).
• Parameters:
• REST – The id of the pet is passed as a path parameter in the endpoint URL.
• SOAP – The id of the pet is passed in the Body block using the GetPet option.

Also Read:?Swagger API: How They Work & What you Need to Know

When to use REST vs. SOAP

REST for public web services

REST and SOAP’s features make them suited for different use cases.

A defining feature of REST is its message format, JSON. REST’s use of JSON makes it well-suited to public web services/Open APIs . The JSON payload is lightweight and small compared to SOAP’s XML payload. JSON is highly browser compatible and is more efficient for web browsers than XML. Furthermore, JSON payloads contain far fewer characters than SOAP payloads because an XML message is more verbose than JSON.

Since SOAP XML payloads also have more overhead to compose them, the preferable route is to incorporate a SOAP library to make API calls in your programming language. While this proves more efficient, it adds another layer of abstraction not necessary when using REST. REST’s constraint of client-server separation discourages the use of client libraries. Client-server separation is critical to web services since they must be portable, scalable, and evolve independently. In addition to using client libraries, you need to use an XML parser on the client side which adds overhead.

A critical issue for web services is resource limitations. While not handled directly by the REST API, clients can effectively cache HTTP responses. Caching is made possible by REST’s separation of endpoints using URLs and its use of HTTP headers to perform CRUD operations.

SOAP is different. When sending a payload to a SOAP API, you target one URL for all requests. Every message HTTP header is a POST header. Most HTTP caches do not cache POST responses, making caching for SOAP impossible (or infeasible). The fact you cannot implement caching for SOAP is a disadvantage for those developing web services.

While REST brings speed and efficiency, it does not support message-level security like SOAP. An API developer may choose REST over SOAP when this is required.

SOAP for enterprise applications

While REST is the best overall choice for web services, namely public web services, SOAP has built-in WS-Security that REST lacks. SOAP is better suited for security-critical applications. Unlike REST, SOAP’s security is message-level.

This added layer of security makes it well-suited for enterprise-level software such as CRM solutions, identity management, banking apps, financial and telecommunication services, or legacy systems.

ACID compliance is built into SOAP, making SOAP attractive for sensitive financial services.

Alternatives to SOAP and REST

There are a few alternatives to SOAP and REST. The most common are GRPC and GraphQL.

gRPC?stands for?Remote?Procedure?Call. This standard is suited for microservices architectures that require lightweight messaging in constrained bandwidth scenarios. You can use gRPC to connect IoT (Internet of Things) devices like smartphones to services in the backend.

GraphQL?is a database query language growing in adoption. Requesting data from a GraphQL API is more efficient than REST. With REST, there are separate resource URLs (sometimes hundreds) that expose the functionality of the API. If you need to gather information from two resources, you must make requests to each resource URL. With GraphQL, all API data is available to be queried using one request. Clients retrieve data from one API using filters that narrow their query.

In Closing

REST and SOAP are both specifications that provide standards for how clients access and interact with web services and the functionality they expose. However, REST is an API architectural style, and SOAP is a protocol for data transmission between a client and a web server. So, comparing the two is not “apples to apples”.

REST was created to improve upon SOAP’s limitations. The benefits of REST make it well-suited for public web services that are resource constrained. REST’s data format JSON is highly browser-compatible and requires less bandwidth than SOAP XML payloads. REST also mandates client-server separation. This constraint is important for web services to function efficiently. While REST, in some ways, has superseded SOAP for public web services, SOAP still sees high adoption for security-sensitive scenarios such as enterprise-level applications and financial services.

Shakeer Hussain

Author

Shakeer is the Lead Product Manager at Document360. Passionate product management professional and Certified Scrum Product Owner (CSPO). Actively collaborate across the organization creating product strategies, roadmaps and plans focused on supporting the business strategy.?View all posts by Shakeer Hussain