API is the abbreviation of Application Programming Interface. APIs specify how different software components should interact and communicate programmatically.

The most common type of API is Web API. Web applications, including websites, send requests to Web APIs or web services to display data to the user. For example, a website will return the best deals on flights, hotels, or car rentals based on your search criteria. The website does not retrieve this data from its database, but obtains the data by sending requests to APIs dedicated to providing services such as flights, hotels, etc. Web API is an API that uses HTTP protocol to transmit data.

The two most popular web API specifications currently are REST and SOAP.

There is ongoing debate as to which architectural style is best for building APIs. Although they are both specifications, they cannot be compared. One subtle difference is that REST is an API architectural style, while SOAP is a protocol for accessing network services. They seem to compete with each other, but both have their own use cases.

This article will explore the differences between the two standards and how to choose between the two protocols.

Similarities and Differences between REST and SOAP

What do REST and SOAP have in common, and why are they often compared?

REST and SOAP are both specifications that provide standards for how users access and interact with web services and the functionality they expose. As mentioned earlier, REST is an API architectural style, while SOAP is a data transfer protocol.

• As an architectural style, REST has certain restrictions on the design of Web API. The REST standard requires that Web APIs that are considered “RESTful” must adhere to REST constraints. These constraints include client and API server separation, statelessness and cacheability, etc.
• SOAP, as a Web API protocol, is a data transmission standard, which stipulates the message:
  1. Format
  2. letter of agreement
  3. processing method. Unlike SOAP, REST does not dictate how to handle API information

Since SOAP is just a Web API protocol, REST API can use the SOAP protocol as the standard for data transmission. However, REST and SOAP are different standards and generally cannot be mixed.

Although one is an architecture and the other is a protocol, both provide standards for API message formats. REST and SOAP’s message formats are readable by humans and machines. For REST, JSON is a lightweight data exchange format that is highly compatible with browsers. For SOAP, XML is an extensible markup language that allows custom descriptive markup for easier reading. These data formats are discussed in detail later.

SOAP before REST

SOAP came before REST. REST is designed to solve some of the problems of SOAP. The goals of REST are to be lightweight, highly compatible with browsers, separate the client from the server, and provide caching capabilities.

So, if REST came after SOAP, and REST solved SOAP’s problems, why does SOAP still exist?

This is because although REST has clear advantages over SOAP, and in some ways, REST is designed to replace SOAP, SOAP still has its uses. For example, SOAP is suitable for enterprise-level applications that require message-level security.

What is a REST API?

REST is the abbreviation of “Representational State Transfer” and is a specific API construction style. APIs constrained by this style are considered RESTful APIs. RESTful APIs must meet the following requirements:

1. unified interface
2. no status
3. cacheable
4. Separation of client and server
5. layered system
6. Coding on demand

REST API is a Web API that uses the HTTP protocol, where the client sends an HTTP data request to the API server, and the server sends an HTTP response back to the client with encoded data.

Clients use “resources” to access and manipulate data exposed by the REST API. Resources represent different API functions and are accessed through resource URLs. Resources can be thought of as data objects returned by an API. When making a request, you pass a method to the resource that corresponds to a CRUD (create, read, update, and delete) operation. Think of methods as “actions” taken on a resource, such as creating, updating, or deleting a resource.

For example, the well-known Swagger Petstore API consists of multiple resources. These resources include pets, stores, and users. All resources are related to the topic Pet Shop, and each resource represents a different data object that you can create, manipulate, or delete.

To request a resource, you send an HTTP request to the resource’s unique URL and specify the action (method) you want to take on the resource. Example operations include creating, updating, querying, or deleting resources (POST, PUT, GET, and DEL respectively).

Advantages of REST API

Separation of front and back ends

The separation of front and back ends has the following advantages:

• Portability of all components. Because the REST architecture is “multi-layered,” server components are portable. The REST API is available on multiple platforms, which makes it easy to test during development.
• Increased scalability by limiting interactions between architecture layers (multi-level architecture) . This limitation simplifies server components. This architecture also increases the flexibility to move data between servers and enable new changes to be rolled out quickly.
• Easier to integrate. REST enables developers to focus more on user interface, functionality, and business rules rather than server components and data management handled by the API server.

Support JSON message format

REST using JSON as the data format has several advantages:

• Browser compatibility : As a data format, JSON is very compatible with browsers and more browser-friendly.
• Low bandwidth usage : JSON is an extremely lightweight and easy-to-parse data format. The XML payload (in the case of SOAP) is larger than JSON. Larger payloads require more bandwidth. The amount of code required to write an XML SOAP request also increases the size of the message.

Information format flexibility

In addition to JSON, REST also provides more information formats, such as HTML, plain text, XML, YAML, etc. The flexibility of message formats makes REST more suitable for public APIs.

What is SOAP?

XML allows the use of custom descriptive tags to store and share information, unlike the predefined tags used by HTML. The standardized nature of XML makes it easy to migrate across different platforms and systems. As a message format, XML provides high flexibility. Users can define XML schemas according to their needs to ensure that the structure of XML messages meets specific requirements.

SOAP API differs from REST API in the way of data access and operation. REST API accesses data through resource URLs, while SOAP API operates on data by calling specific API functions.

Unlike REST, CRUD (create, read, update, delete) operations are not directly included in SOAP requests. Instead, these operations are implemented by calling different functions. For example, in a REST API, you usually only need a URL endpoint to create or update a resource by sending a POST or PUT request. In SOAP, creating or updating a data object requires calling separate functions that handle these specific operations.

XML messages are primarily transmitted via the HTTP or HTTPS protocols. But it’s worth noting that the SOAP API also supports other transport protocols such as Transmission Control Protocol (TCP), Simple Mail Transfer Protocol (SMTP), and User Datagram Protocol (UDP). In contrast, the REST API is limited to the HTTP protocol.

Advantages of SOAP

Stronger security

SOAP is well suited for security-conscious web services because it uses WS-Security (as well as SSL) and has built-in ACID compliance. REST does not have these capabilities. WS-Security is a specification for signing and encrypting SOAP XML messages. The header block of each SOAP request contains the security information required to complete the request. ACID compliance is a set of standards for protecting the integrity of databases. Many enterprise and financial trading applications require ACID compliance.

Flexible transmission channels

SOAP supports multiple communication protocols. REST only supports HTTP. With SOAP, you can use HTTP, HTTPS, User Data Protocol (UDP), Transmission Control Protocol (TCP), or Simple Mail Transfer Protocol (SMTP).

Anatomy of REST

The REST API consists of the following parts:

• Request method: The CRUD operation you wish to perform on the resource. In this example, the HTTP method POST indicates that you want to create some content.
• Endpoint: The specific endpoint of the resource (resource URL). In this example, the endpoint is petstore.swagger.io/v2/pet. Resources are data objects returned by the API and can be located using endpoints.
• Request header: Specify the information format, in this example, JSON format. You can pass the authorized tenant (such as API key) in the request header.
• Request body: Contains a JSON object containing the properties of the new resource. In this example, the request body contains the details of the new pet. Request bodies are similar to parameters, except they are objects containing multiple properties instead of one.

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

Anatomy of SOAP

A SOAP XML message contains the following “chunks”:

• Envelope: A required part that identifies this XML message as a SOAP message (unlike other XML messages). Its namespace attribute points to the latest version of SOAP.
• Header (request header): Optional part used to store authorization attributes, such as API keys, etc.
• Body: Required section that specifies what information is expected to be received back from the API after submitting the request. This section includes the function name (procedure) and the parameters you wish to pass, which will affect the result. In the response, the Body section contains the API’s response and the requested information.
• Fault: Optional part. If the SOAP API cannot handle the request, it sends the error message defined here. There are many reasons why a request may fail; for example, the message structure may not conform to the XML schema definition.

To understand the structure of SOAP, let’s compare REST messages with SOAP messages. Below is a REST API cURL request to the Swagger Petstore API that retrieves a pet based on petId. petId 1Is a path parameter placed at the end of the requested resource URL.

Here is the SOAP structure of the same request to show the difference:

Here are their differences:

• Information format:
  • REST – cURL is a tool for constructing HTTP requests, but you can also use a variety of programming languages ​​to send REST requests. The message payload (that is, the message body) of these requests is typically in JSON format.
  • SOAP – Message format is XML. XML structures are implemented by XML schemas.
• Request method (CRUD operation):
  • REST – Provides a GET method in the request to tell the application interface to retrieve some content.
  • SOAP – No method provided in the request. The request is sent to a procedure that handles retrieval (GetPet function).
• parameter:
  • REST – The pet ID is passed as a path parameter to the endpoint URL.
  • SOAP – Use the GetPet option to pass the pet ID in the Body block.

When to use REST vs. SOAP

REST for public web services

REST is well suited for exposing web services and open APIs because it uses JSON as the message format. JSON’s lightness, compactness, and high compatibility with browsers give it more advantages than SOAP’s XML format. Additionally, SOAP’s XML messages are verbose, while JSON is more concise.

When processing SOAP XML messages, due to the complexity of its composition, it is usually necessary to integrate a SOAP library in a programming language to make API calls, which relatively increases the abstraction layer and processing overhead. In contrast, the principle of front-end and back-end separation advocated by REST does not rely on client libraries, thereby maintaining the portability, scalability and independent development of network services.

In resource-constrained web serving environments, REST also has the advantage that clients can efficiently cache HTTP responses. This is accomplished by REST using URLs to separate endpoints and leveraging HTTP request headers to perform CRUD operations, while SOAP is difficult to cache due to its POST request method.

Enterprise-level applications prefer SOAP

While REST excels in public web services, SOAP is more advantageous in security-critical applications due to its built-in message-level WS security. This additional security makes SOAP more suitable for enterprise-level software, such as customer relationship management, identity authentication, banking applications, financial and telecommunications services, and integration with traditional systems.

Additionally, SOAP has built-in ACID compliance, which is particularly attractive for sensitive financial services. Therefore, in enterprise-level applications, SOAP is often favored for its strong security and transaction processing capabilities.

Alternatives to SOAP and REST

In addition to SOAP and REST, there are other common choices such as GRPC and GraphQL.

gRPC is a standard that is ideal for microservice architectures that require lightweight messaging with limited bandwidth. You can use gRPC to connect IoT devices such as smartphones with backend services.

GraphQL is an increasingly popular database query language. Requesting data from a GraphQL API is more efficient than using REST. When using REST, there are individual resource URLs (sometimes as many as hundreds) that expose the functionality of the API. If you need to collect information from two resources, you must make a request to each resource URL. With GraphQL, all API data can be obtained through a single query request. The client retrieves data from an API using filters to narrow the scope of the query.

Summarize

Both REST and SOAP provide standard specifications for client access and interaction with Web services and the functionality they expose. However, REST is an API architectural style, while SOAP is a data transfer protocol between the client and the web server. Therefore, comparing the two is not entirely apples-to-apples.

REST emerged to improve upon the limitations of SOAP. The advantages of REST make it well suited for resource-constrained public Web services. REST’s data format, JSON, is highly browser-compatible and requires less bandwidth than SOAP’s XML payload. REST also enforces the separation of front-end and back-end. This constraint is critical for the efficient operation of network services. Although REST has replaced SOAP in public network services in some aspects, SOAP still has a high adoption rate in security-sensitive scenarios, such as enterprise-level applications and financial services.