A new contender
I was watching Hi Score Girl season 2 recently so I am in the fighting games mood. Someone pressed start on player 2 controller and now there is a new contender in the API building space. Well the pressing of start was already done a long time ago, but it seems more and more people are just now starting to watch the cabinet that is hosting this battle.
I am talking about GraphQL vs REST. There seems to be more people that go down the GraphQL path and like usual it seems everyone is stating that it should be the only way now to build APIs. So what makes it stand apart, well mostly due to two things.
Entity management
So in REST you normally have to create the relationships yourself on the frontend and in the code there is a lot of boilerplate that links endpoints to entities and what you can do with them. What happens though if you have a lot of nested entities. Like for instance let us say you had to go via users into posts into comments by doing : /users/<id>/posts/<id>/comments ? That is quite a long url, and so what happens is the following. You have an endpoint for comments and you give it the post id, but how do you know how to get that? Well you list all the posts on it's endpoint and you can see that there is some manual crafting involved in the frontend application in order to consume this API.
In GraphQL this pressure lies in the backend, where you hook up all the entities together in some form and then the frontend can just consume the API and pick and choose when to show what properties of the DTO. In addition you can generate the TypeScript for this API for example and then the frontend does not have to write any boilerplate. This is quite flexible and powerful, but comes at a cost.
Database calls
In general a certain REST endpoint will result in one or maybe a few calls to the database to retrieve the data. In GraphQL this can result in an explosion of database calls as it walks the tree by going all the way to the first leaf and then up one, and down one and so on. So called Depth First Traversal.
There are two ways to solve this, by doing Breadth First Traversal, or using the Dataloaders concept of GraphQL. The Dataloaders are a utility that will hold an internal cache and so will only query the database once if it has the result for a query done previously. This means that the number of queries will go down considerably. Just make sure the Dataloader instances are global and therefore all queries can make use of them.
The Breadth First Traversal would entail that first you get all the nodes in the first layer and with those ids go to the second layer and query them all there and so on downwards. This will make the number of queries go down to number of layers.
When to use
So the question becomes when do you use what tech? Well if you can handle the extra pressure on the backend and the data is quite nested and potentially complex, it might be a good idea to go for GraphQL then. Otherwise stick to REST as it is easier to setup, but requires a bit more boilerplate in the frontend.
There is always RPC for those other cases where entity management is not even an option and you want to interact with executing functions directly where the action is more important than the entity itself.