GraphQL vs REST
Our .NET developer Oleg Gavrilov is sharing his experience about GraphQL:
A bit of background: GraphQL is a query language created at Facebook in 2012. The language provides users with the description of the data of your API and let them request exactly what they need.
The problem being solved by language creators was the conflict between users’ wish to get all information with one query and the requirement to isolate resources in traditional REST.
From my own experience: if you ever had to choose between API comfortable for users and “the right REST”, you should absolutely read this article first.
And that resulted in an interesting alternative to REST-approach with elaborate specification and quite innovative solution for the data query issue.
A curious fact: the first issue solved by GraphQL was transitioning Facebook’s iOS app news feed from WebView to a native UIKitrenderer. How many queries to REST-services are necessary to get all data about latest posts with comments, likes, images, links and so on? In case with GraphQL only one query would be needed due to its graph model of data description and support of obtaining embedded entities with a root object.
Here comes an obvious advantage of GraphQL – applying this technology yields tangible results when working in slow networks with long delays (like cellular networks still are).
From my own experience: once we were developing a solution that has to work with any network conditions, for instance, via GPRS. Handling all unnecessary queries to the server affected efficiency a lot – a network delayed each query up to 2 seconds. Initially we planned to respond to query with all potentially needed data but soon it ended up with delay due to a big volume of unnecessary information responded to a user “just in case”. Instead of response-shaping we chose GraphQL and that solved all problems.
One more key advantage is also the amount of data sent. A user has an opportunity to get only what he wants. For example, when requesting for goods catalogue one doesn’t have to get the description of each product.
Besides the collaboration between frontend and backend developers reduces – if the data scheme is stable, GraphQL allows not to distract server developers with changing users’ requests – you may just change the query and get the data you want.
From my own experience: if you spend more than two hours per week on coordination of API changes upon the demand of the developers of client-side applications, GraphQL can help you.
As any technology GraphQL is not free from shortcomings. All of them can be fixed somehow but it would be useful to be aware of them in advance.
As I see it the first issue is a strange approach to updating data. The mechanism of mutation is supposed to be used – these are special methods with fixed data model. The approach is similar to JSON-RPC – kind of a step backwards for the developers who prefer to work with REST API.
From my own experience: I had a chance to be a part of a team developing a software product supporting both GraphQL and a major version of REST. The reason was that under the scope of the project GraphQL was ideal for data reading but REST – for data changing.
The second issue (that REST also has) is a complete lack of data schema versioning or evolving. The solution could be either creation of “a new version” of the model that will be working in parallel with the old one or expanding the existing model with new fields and supporting the behaviour of “deprecated” fields.
The issues with caching replies, data encapsulation, “N+1” queries, checking of fair use are worth mentioning but they are specific for each project and unfortunately I can’t recommend you any generic solutions for them.
From my own experience: for example, Instagram works via GraphQL, but publicly available API to their service is implemented with REST – but there is some way to get “private” GraphQL API and get much more information than if using publicly available API.
The bottom line is the following and you may decide if GraphQL is worth using:
If creation of “the right” REST API gives you more troubles than benefits.
If the effective communication between frontend (mobile) and backend developers is troublesome.
If the data model is fixed and won’t change.
If you think that REST is boring and JSON-RPC is underestimated, but you want to use something modern not to fall in your colleagues’ esteem.