The Ultimate Guide to API Architecture: REST, SOAP or GraphQL?

For many years, the API world was resting on two major pillars – SOAP and REST. SOAP (Simple Object Access Protocol) was invented in 1998, and REST (Representational State Transfer) – in 2000, and for many years they were dominating everything related to application programming interfaces.

However, in 2015 Facebook released GraphQL, a new data query language that is said to be an alternative to REST and SOAP. Usually, when people start looking for something new, it means that current solution is not enough. In the context of API protocol, the introduction of GraphQL can mean that REST is no longer up to the task and that GraphQL is better. But is that so?

We will look into the very core of REST, SOAP and GraphQL to see how they are different and what can be the best way to exchange data between applications.

Basics of SOAP, REST and GraphQL

api-architecture-rest-soap-graphql-overview

Although all three of them are used to create API architecture, they have some major differences starting with their nature. SOAP is a protocol, REST is an architectural style, while GraphQL, as we can see from the “QL” in its name, is a query language.

  • SOAP operates with the two basic functions – GET and POST. GET is used to retrieve data from the server, while POST is used to add or modify data.
  • REST, in its turn, changes the state of the corresponding source by making a request to the URI (Uniform Resource Identifier).
  • GraphQL leverages requests of two types – queries retrieving data from the server, and mutations changing the data.

The major conceptual difference between the three protocols is that SOAP performs operations representing logic, while REST and GraphQL operate with resources representing data.

API Protocol Comparison

If we start comparing the existing API protocols, we can easily see how the concepts and approaches of API architecture have evolved over time and what issues each new protocol has been solving.

REST vs SOAP

The key difference between SOAP and REST protocols lies in their approach to handling the app payload. SOAP, with XML used as data format, is far too verbose, both on the request and the response side. The amount of data transferred within the SOAP structure was enormous, thus requiring more resources and slowing down the communication.

With the advance of mobile applications, this approach has quickly become inefficient, as it affected their performance. REST with its endpoint requests seemed to be a silver bullet, thus has rapidly turned into the protocol of choice among open API architecture developers.

Below is an example of a SOAP request and response. As you can see, both messages are quite extensive and contain a lot of data.

api-architecture-rest-soap-graphql-request-response

Image credit: CodeProject

A REST request, on the contrary, is more efficient, since its structure is more plain and obvious. It contains all properties of the requested resource, no matter whether the user needs it or not.

api-architecture-rest-soap-graphql-comparison-example

Image credit: Atlassian

Another disadvantage of SOAP was its support of a single data format, XML, while REST could process XML, HTML, and JSON.

REST vs GraphQL

While REST was a kind of a technology breakthrough in the area of API-oriented architecture, it still left developers wanting more. When Facebook guys started looking for a different way of fetching data from the server, they were trying to resolve the problem of under-fetching or over-fetching that the existing API protocols had. In REST or SOAP, a request for certain data returned all properties associated with it, even those the user did not need.

For example, in REST, if you requested a list of products and their prices, you would also get product descriptions and images, if available. At the same time, if prices were quoted in another source, you would have to make another query to retrieve them.

GraphQL was designed to take care of this problem. When you make a data query in GraphQL, you specify exactly what you wish to receive. Such results are achieved through shifting the data definition functions to the client side, while in REST, data is defined on the server side. In other words, in REST API architecture, the server defines which data is to be returned, while in GraphQL API, the server only declares the available data, and the client specifies what should be returned.

api-architecture-rest-soap-graphql-example-code

Image credit: Atomic Object

This is how GraphQL works. Moreover, it can fetch data from different databases by a single query.

Another thing you should consider while choosing the API protocol is data caching. Caching eliminates the need to send full requests and responses in case data has been cached from previous requests. REST API uses the HTTP caching mechanism that provides quite satisfactory results. At the same time, GraphQL has no inherent caching and requires additional mechanisms on the client side, such as Apollo Client.

SOAP vs GraphQL

GraphQL, being the latest innovation in the API architecture evolution, combines the strong suites of both SOAP and REST. If we compare GraphQL and SOAP, we will see that both use single endpoint URLs to fetch or modify the data. At the same time, GraphQL is much more lightweight, thus reducing the network payload.

Another similarity between GraphQL and SOAP is strong data typing. Both protocols declare data types explicitly, which ensures better communication between applications.

Having mentioned caching as one of the points worth taking into account, we have to admit that in this respect both SOAP and GraphQL have nothing to boast of. Neither of them has own caching mechanisms and needs to rely on additional tools.

Advantages and Disadvantages of SOAP, REST and GraphQL

Now that we have seen how the three API protocols are similar or different, let’s identify their strong and weak points to conclude when each of them should be used.

SOAP

Advantages
Disadvantages
  • Single endpoint used for retrieving data
  • Only one data type supported (XML), thus limiting the possibilities
  • Strong data typing enables seamless communication between applications using SOAP API architecture
  • Extreme verbosity results in excessive data sent in both requests and responses. This can create too much load on the network and affect the application performance
  • Use of different communication protocols
  • Server-side data definition causes data over-fetching or under-fetching

 

  • No caching mechanisms

REST

Advantages
Disadvantages
  • Support of multiple data formats
  • Weak data typing that may cause communication problems between applications, even those supporting REST API
  • Lightweight structure reduces the network payload and ensures optimal application performance
  • Data over-fetching or under-fetching
  • HTTP caching allows reducing the amount of data sent and received
 

 

GraphQL

Advantages
Disadvantages
  • Strong data typing
  • Lack of versioning support leaves developers with no clear indications of deprecated fields or values. With no versioning, the developers using GraphQL cannot know when they need to update their application with the API change
  • Client-side data definition allows fetching exactly the requested data. This data fetching approach greatly reduces network payload and increases application performance
  • No caching mechanism. Caching setup requires implementation of additional tools
  • Single endpoint used for retrieving data
  • Need to learn a new API protocol. Although GraphQL is rather easy to learn, it is still a new protocol requiring certain preparation before you can start using it properly
  • Search on multiple databases with a single query
 

 

The table below summarizes the most prominent features of all three API protocols and can help you choose the one that will suit your purposes best.

 
SOAP
REST
GraphQL
Year of release199820002015
TypeProtocolArchitectural styleData query language
Accepted data formatsXMLXML, HTML, JSONJSON
Communication protocolTCP, HTTP, SMTPHTTPHTTP
Data typingStrongWeakStrong
Data definitionServer sideServer sideClient side
Endpoints SingleMultipleSingle
CachingNoYesNo
VersioningYesYesNo

When to Use SOAP, REST or GraphQL?

This is the big question, as we compare the protocols and find their advantages and disadvantages for a single ultimate purpose – deciding which of them to use in a particular case. Therefore, we have put together a small list of recommended use cases for each of the API protocols we have analyzed.

api-architecture-rest-soap-graphql-application

  • SOAP can be used in enterprise solutions with formal contract-based exchange formats. Also, SOAP APIs perform best when there are acceleration mechanisms implemented on both sides.
  • REST is very JavaScript-friendly, so it is a perfect choice for JavaScript-based applications. Besides, it can cope with higher loads and process data quicker than SOAP. Thus if your application is rather load-intensive, REST may be your API of choice.
  • GraphQL can show the best performance when the number of queries needs to be reduced to the absolute minimum. With its single query addressing multiple resources, GraphQL can be a good match to this challenge. Also, considering the fact that in GraphQL data is defined on the client side, it can be a good solution for cases when there is no dependency between the client application and the server.

In conclusion, we would like to say that, as everywhere in custom software development, there is no universal solution in the choice of protocols for creating web API architecture. Each application is unique, and your decision should be based on what is best for your project. Moreover, you can combine API protocols to achieve the most optimal results.

↑ Go up

Similar post