1. Introduction
API (Application Programming Interface) is a part of the software that receives requests and answer with responses. It allows multiple software components to communicate with each other. Nowadays, APIs are crucial while developing applications, especially web and mobile ones.
In this tutorial, we’ll analyze the two most known approaches to building APIs called REST and SOAP.
2. REST
REST (REpresentational State Transfer) is an architectonical style of creating APIs. In simple words, it’s a set of good practices for developing scalable, reliable, and maintainable web services. Applications that follow REST conventions are called RESTful. It’s important to say that REST isn’t a standard. It gives flexibility while developing API’s features.
REST can work with a variety of protocols such as HTTP, SMTP, or FTP. Moreover, it can use many formats to transfer the data, e.g., JSON, XML, HTML. Although, most of the time, RESTful web services work with HTTP and JSON. Applications with other configurations are not typical.
As we mentioned earlier, REST is adjustable. There is a set of guidelines that API must follow to be called RESTful. Let’s describe them.
2.1. Core Concepts
First of all, RESTful APIs must follow client-server constraints. It provides scalability and portability. Hence, the client’s side can be easily extended with new platforms. In other words, multiple client applications can use a single API, maintaining data consistency.
Secondly, the Restful API must be stateless. The server can’t store any information about the user’s session or intermediate states. Thus, each request is independent and contains all the necessary data to respond to it. Each request can fail due to problems, for instance, an unstable network connection. If multiple requests would be needed to handle one task, the risk of failure increases. So, statelessness improves reliability.
The third important thing is cacheability. Client applications can store the data that doesn’t frequently change. Consequently, it boosts performance by decreasing the number of requests sent to the server. The server is responsible for marking the response as cacheable or non-cacheable. Therefore, it prevents the client from caching inappropriate data.
Next, the RESTful API must be designed as a layered system. Separation of concerns improves security and scalability. Client applications shouldn’t know if they connect directly to the server or intermediaries. Hence, we can easily add middleware, for example, load balancers, authorization servers, or shared caches.
Finally, the crucial constraint of REST is the uniform interface. Any resource should be represented by a single logical URI. Moreover, it should provide information on how to fetch related resources. Further, the representation of the data returned by API can’t depend on the database schema.
2.2. HTTP Request
As we already mentioned, RESTful APIs most often uses HTTP protocol. So, let’s analyze the structure of an HTTP request to the RESTful API. It consists of the following elements:
- The request method specifies an operation type that will be executed on a resource. The most fundamental ones are POST, PUT, GET, DELETE
- Headers are key-value pairs of additional metadata. They’re optional, so there can be zero or more. The HTTP specification defines available headers
- The resource path is a URI describing a specific resource
- The optional body contains data necessary to handle the specific request
Now, let’s see a real-world example of such a request.
POST https://jsonplaceholder.typicode.com/posts
Accept: application/json
Body:
The above request creates a new resource, the example blog post. We’re using a POST HTTP method, and we’re sending a request to the following URI https://jsonplaceholder.typicode.com/posts.
The request consists of a single header Accept: application/json. It informs the server that the client only supports JSON data format as a response.
Finally, we have a body with a blog post data that we want to create. The JSON contains three fields, title, body (blog post content), and userId (of the author).
3. SOAP
SOAP (Simple Object Access Protocol) is a messaging protocol created by Microsoft to transfer data between peers in a distributed environment. It aims to afford independence, neutrality, extensibility, and verbosity. In contrast to REST, SOAP is standardized. So, it isn’t flexible, and given constraints must be followed scrupulously. SOAP can work with a few different protocols but most often is paired with HTTP. In contrast to REST, it supports XML as a data format exclusively.
SOAP is a heavyweight protocol. It uses XML as a serialization format. XML is much heavier than JSON mostly because it contains a lot of boilerplate code. Furthermore, SOAP uses WSDL (Web Service Documentation Language) to describe the API. WSDL is a documentation XML file that is complex and thick. Although it isn’t required, it’s usually used and demanded.
Despite these drawbacks, SOAP is a safe and reliable protocol. Large enterprise applications often use SOAP due to its standardization and security.
3.1. SOAP Message
Let’s analyze the anatomy of a SOAP message:
The SOAP message consists of the following elements:
- Envelope – describes the XML document as a SOAP message
- Header – an optional block that contains additional metadata, for instance, timeout
- Body – carries request and response data
- Fault – an optional block that provides information about errors that occurred during the process. If present, it lies within the body
The SOAP message is described by the following constraints:
- Must be an XML document
- Must contain an envelope
- Can have a header
- Must have a body
- Must use envelope namespaces
- Don’t need to have a DTD reference
- Don’t need to have XML Processing Instructions
- Must use encoding namespace
Let’s see an example of a SOAP message. The below document requests a price of a bicycle.
<soap:Envelope>
<soap:Header>
<maxTime value="10000"/>
</soap:Header>
<soap:Body>
<GetPrice>
<Name>bicycle</Name>
</GetPrice>
</soap:Body>
</soap:Envelope>
So, in the example, we have a SOAP envelope with a header and a body. The header contains the maxTime tag, which describes the value of maximum milliseconds that the sender will wait for the response. Then comes the body, which contains the GetPrice block. It specifies the API’s method we want to reach. In the GetPrice block, there is a Name attribute. It’s a parameter pass to the API’s method with the value of a bicycle.
3.2. WSDL
We mentioned earlier that WSDL is the documentation of a SOAP-based web service. Moreover, there are tools, like SoapUI, which provide the possibility to generate a source code basing on the WSDL file. The WSDL file provides the following information:
- Services provided by a web service
- How to invoke available operations
- Location of the web service
Follow our article to read more details about creating WSDL documentation.
4. REST vs. SOAP
We already know the fundamentals of web services created using SOAP or REST. Both of them are well-established ways of creating web services. Although they slightly differ from each other. Let’s compare their most important features to consider while creating a web service.
First of all, REST is elastic in terms of the data format of transfer data. Different endpoints of REST-based API may even accept several formats. On the other hand, SOAP allows only XML format of messages.
SOAP provides additional layers of security due to WS-Security extensions. That protocol applies embedded security mechanisms to web services. Moreover, it describes the integrity and confidentiality of messages. Using REST implementing a similar level of security may be harder and more time-consuming to achieve. It is worth noting that both REST and SOAP support SSL.
If the performance is the main issue, REST would be a better choice. It’s lightweight, and it supports light data formats. Thus, it requires less bandwidth than SOAP. Moreover, REST supports caching, which can slightly boost the performance of a web service.
Finally, it’s important to notice that REST is stateless. Consequently, stateless APIs are easier to scale and extend. However, there are cases when managing the user’s session on the server-side is preferred. The SOAP can be either stateless or stateful, depending on the implementation.
5. Conclusion
In this article, we deeply compared REST and SOAP. Firstly, we introduced REST and its core concepts. Then, we analyzed a simple example of an HTTP request to a REST-based web service. We described SOAP fundamentals. Subsequently, we investigated an example of a SOAP message. Next, we briefly defined a WSDL file and its purpose. Finally, we compared the crucial features of SOAP and REST.