REST API, GraphQL or SOAP — Which is the best?
APIs are an absolute innovation for the internet and many developers. A digital world without APIs is unimaginable! Why? Because APIs take work off. The exchange of information became a lot easier and more efficient. But what if it comes to write an own API? — Well, there are many different types of an API. But which one is the best?
There is a short answer: It depends on what you want to do with your API and on the functionalities and requirements on your API. There is not that perfect API. For comparing these technologies, we need an example:
Let’s say we want to create an API that sends article information to your client. But your client does not want all article information. The client only wants specific information about his requested article and not of the whole store. If you’re in a shop and want to buy a red shirt, you might not want to know the price for a blue shirt but for the red shirt that you want to buy.
This means that our API has to be capable to send information about a specific requested article with specific requested details. Let’s call them information fields. Information fields can be a name, a description, a price or anything. But these fields have to be correctly indentified by the API.
So… which API type is the best for this job?
What about REST?
A REST API (Representation State Transfer) or RESTful API is a architectural style that follows specific constraints that are definded by this REST architectural style. With a REST API you are able to interact with RESTful web services.
Such a REST API works with HTTP which means that you can work with HTTP verbs like POST, GET and more. The principal of REST is that the clients sends a HTTP request with the operation that he wants to make. In this way the client is capable of reading and manipulating resources (information). These resources are identifiable. The client can also do this with hybermedia such like images. [1]
Sounds good? Not at all…
When a client makes a request, he gets all information about the requested resource of the server. But the clients only wants specific information. This problem is called overfetching: A client recieves more information than he requested. [2] This can cost a lot of performance issues. Especially if you take a look at mobile devices. This will cost a lot of traffic data.
This is not the best solution for our example case.
Maybe SOAP?
SOAP (Simple Object Access Protocol) is a standard protocol system with protocols for accessing web services over HTTP. It defines how web services communicate with each other or with other clients. SOAP is designed for working with different applications that are written in different programming languages. [3]
An API with SOAP comes with high security standards because it supports SSL and it has a built-in ACID compliance. Like REST, you can use HTTP verbs for interacting with the API. [4]
The problem with SOAP APIs that their performance needs more bandwith and computing power. Unfortunately, this is a big disadvantage when the clients mostly use mobile phones. Another disadvantage is that the only supported message format is XML. This means it is less flexible than other API technologies. [4]
All in all, for our example case where we need a good API performance, SOAP won’t work well. And you cannot choose the message format that you want.
Or GraphQL?
Another API technologie is called GraphQL. In comparison, GraphQL has been existing since 2015. GraphQL is a query language for an API which is designed for getting the exact information you need. A GraphQL works with queries for getting and sending information to the client. Additionally, different fields that contain information are defined which the client can request. GraphQL differs between unique resources. For example, you can use IDs for correctly identifying a resource. When using GraphQL you can almost use any programming language you want and you can decide in which format the client requests and recieves information. [5]
To put it in a nutshell, the big advantage of a GraphQL API is that the client only gets the information he needs or requested. The GraphQL API is capable of identifying a resource and it sends only the requested information of the requested resource. This means that GraphQL APIs does not have the problem of overfetching or underfetching. As a result of this, the performance of this API can be better then REST or SOAP APIs. [5]
In my point of view a GraphQL API would be the best decision for our example case, because our main requirements were that the client only gets the information that he actually needs and only of the resource he requested. This causes a good performance.
The comparison between REST, SOAP and GraphQL is only a small comparison. There are many more things to consider when choosing the “right” api technology for your project. Personal preference and knowledges are also important for your decision. Regarding the example case, there are may programmers that have a different point of view. There is no “right” API technology. So it is completely up to you what you want to use and what you feel comfortable with.
Here are some resources:
[1] What is a REST API? (o. D.). Redhat. Visited at 18th of March 2022, by https://www.redhat.com/en/topics/api/what-is-a-rest-api
[2] Annoying REST problems. (o. D.). Learngraph. Visited at 18th of March 2022, von https://leapgraph.com/what-graphql-solves/
[3] Walker, A. (2022, 12. Februar). SOAP Web Services Tutorial: What is SOAP Protocol? EXAMPLE. Guru99. Abgerufen am 19. März 2022, von https://www.guru99.com/soap-simple-object-access-protocol.html
[4] SOAP vs REST vs JSON — a 2021 comparison. (2021, 5. März). Raygun Blog. Abgerufen am 19. März 2022, von https://raygun.com/blog/soap-vs-rest-vs-json/#table
[5] GraphQL | A query language for your API. (o. D.). GraphQL. Abgerufen am 19. März 2022, von https://graphql.org/
