Author: Sander van Laarhoven

What is GraphQL?

More and more often you come across GraphQL at conferences and implementations of software. What exactly is it, and what are the pros and cons of using it. Hopefully that will become a bit clearer in this article. It is not a course, but it does give a bit of an idea of how it works and whether it would be suitable for a particular situation.

Origin

GraphQL is a so-called "data query language". It is made to run powerful queries to the backend, while still being easy to use and learn by developers.

It was initially created as an internal project for and by Facebook (2012) and then opened up for public use (2015) (https://engineering.fb.com/201...). After this, the open source community embraced the product and built runtimes for it in various languages, including: Go, Ruby, Scala, Java, .Net and Python.

What is GraphQL

We use a simple application as an example:
In a sales application, the name of the sales employee is displayed on the screen. Of course we do not only want to see the name of the employee in this screen but we also want to have his sales data for the past two years to show at the top of the page. And to give an overview of his most recent accounts, we also retrieve his accounts from the server.

This would be the picture for the described functionality using GraphQL:

In the query of the GraphQL request you indicate what you are requesting from the server, in this case a "user" with id: "k7690cbl789

Then you indicate what information you want to get back for this user.

You therefore do not get more or less than the information you really need in that specific case. And all this without creating a new service on the server.

GraphQL uses a "strong type system" to define the API. All types accessed through the API are put into the scheme using the GraphQL Scheme Definition Language (SDL). This scheme acts as a contract between the client and the server for how a client can query the data.

An example of such a scheme for "user" would be for example:

This ensures that all parties involved know for sure that a "name" field is or must always be a "String". So if a different type of field is offered for the creation of a new "user", the validation in the service will automatically indicate that this is not possible because the field can only be a "String".

GraphQL always works the same for every developer so it is very predictable and there are much less misunderstandings and miscommunications about implementations.

It's not just that we can retrieve multiple things from one specific element at the same time. All data that has been disclosed can be retrieved simultaneously. There is one URL (GraphQL endpoint) that people communicate with. By including a query in the request to the GraphQL endpoint, you indicate what you would like to receive from the server.

For example, if I wanted to have all accounts, users, and company bikes of a company and they are unlocked through the endpoint, I could do that in a single request:

With GraphQL, the structure of the data is described in the schematic. As a result, we see that the same data structure is used in both the query and the response. The elements are displayed hierarchically within this structure because they are also included in the schematic in this way.

Two types of operations are possible within GraphQL. Until now we have only talked about a query, but of course things can also be stored via the protocol. Creating, modifying and deleting data is done by means of a mutation. Query variables can be given in a mutation that are used to modify the data.


For example, a mutation to modify a user's data could look like this:






The information can be provided with query variables:





In the browser this will be translated into another POST with a request payload:






Only a communication protocol

GraphQL is purely a communication protocol and does not say anything about the way the data is stored. It can also be used on top of an existing backend in which all this has already been created.

A GraphQL runtime can make use of existing REST services and open them up as a GraphQL endpoint to a frontend. This can even be done with multiple REST APIs at the same time.

For example, an address can be retrieved and the current local weather via another source. And all this in one request.


Error handling

GraphQL uses a "strong type system" to define the API. All types that are accessed through the API are put into the schema using the GraphQL Schema Definition Language (SDL). This scheme acts as a contract between the client and the server for how a client can query the data. Thus, when communicating in a way that does not conform to the defined schema, a structured specific error message can be generated by GraphQL indicating exactly what is wrong. Developers do not have to make this themselves as with a REST service and can assume that data meets the criteria in the scheme.


Performance

Of course there is a small performance penalty when implementing GraphQL because it is an extra piece of software on top of the data on the server.

Not having to do multiple requests but being able to retrieve everything in 1 request does offer a lot of performance gain, although creating a specific REST API made for that specific purpose can of course be even faster.

In addition, there is no overfetching (downloading data that you do not use), so that the bandwidth and both systems are less taxed.

Underfetching is also not an issue with GraphQL since all data can be immediately retrieved in one request and therefore no additional information needs to be retrieved as an extension of previously retrieved data.

A disadvantage is that all combinations of data can be requested and it is therefore very difficult to predict how much and which data each request will request from the server. It may therefore be the case that certain request or combinations of requests turn out to be very heavy for the server. This also makes request optimization more difficult.

Caching GraphQL requests is a lot more complex than, for example, REST. Normally it is cached based on a unique URL, for example: "/ V1 / users / <id>". With GraphQL this is not possible because the endpoint is always the same. So it will have to be done based on the query in the body of POST that GraphQL is doing. GraphQL APIs therefore create such a unique identifier from the request payload themselves. Although this makes it possible to cache requests with GraphQL, there are of course many times more combinations of fields possible than with a REST API and the potential will therefore be less effective.

Use of GraphQL tends to be (more) heavy on the server, making caching and optimization extra important


Faster independent development

As a front-end developer, you cannot immediately switch quickly with the developer (s) of the back-end in all situations, or the back-end is even under your own management. This sometimes makes it difficult to quickly achieve desired changes to a service for functionality in the frontend. This often causes delays in a development process.

If several parties use the same API, the backend and frontend developers work at a different pace or not in the same team, it can also be difficult to change services. The software on the other hand could eventually stop working because of the adjustment.

With GraphQL you are completely free to access other data within what is made available without having to adjust the service. This means that developers of the different layers of an application need to consult less often and can operate much more independently.


Documentation

Where software often lacks good documentation, GraphQL has already arranged "out of the box" by the scheme and type of system.

Because everything is already laid down in the diagrams, GraphQL can generate documentation itself. The tool used with which queries and mutations can be written, tested and in which the documentation can be viewed is GraphiQL.

This means that the documentation is always up to date and transfer is much less intensive between the backend and frontend developers. After the schedule has been drawn up, both parties can work independently.


Analytics

Because a client will always only retrieve what it needs, it is also possible to see much more specifically on the backend which data is used. For example, fields that are never used can be removed over time.

GraphQL uses so-called "resolver functions" to collect data. By monitoring the performance of these "resolver functions", it is easier to identify areas for improvement in the underlying system.


Flexibility

On the frontend, working with GraphQL is very flexible because you can request everything in any combination you would like. This is a bit less on the backend because you also have to create the schedule there and then work according to the schedule. Saying this, there are a lot of ways to generate business these days. This is made possible by the GraphQL strongly typed schema. This reduces a lot of complexity, but it is still more complex than, for example, creating a REST service.


Complexity

Although working with GraphQL on the frontend is very easy and clear, it does give the backend some extra complexity and of course a schematic has to be made. Optimization of requests is also more difficult in the backend since it is impossible to predict which data will be requested at the same time. Of course, queries that come back regularly or turn out to be less efficient can still be optimized. This will then have to be apparent from the analytics and therefore makes monitoring extra important.


Applicability

GraphQL is particularly suitable if there is a clear separation between frontend and backend teams or if this is even done by different parties. It is also very suitable for opening up an API to the outside world outside the sphere of influence of the party that discloses the data. For very small REST APIs or REST APIs that are called exceptionally often and never change, the extra complexity and the performance penalty make it less suitable. Of course, you can still choose GraphQL because the developers are only used to working with it or because it is the standard.

Specific questions?

Enter your e-mail address and Oliver IT will contact you as soon as possible!

Done! We will contact you soon!
Peter Schults SAP Net weaver expert
Peter Schults