18 February 2021
Just recently our GO Dev team embarked on a project to integrate Monday.com cloud service to one of our internal components. Their API was GraphQL and that’s why we came to work with this technology.
GraphQL is an API standard that provides a more efficient, powerful and flexible alternative to REST. It was developed and open-sourced by Facebook. At its core, GraphQL enables declarative data fetching where a client can specify exactly what data he needs from an API. Instead of multiple endpoints that return fixed data structures, a GraphQL server exposes only a single endpoint and responds precisely with the data the client asked for.
In this technical article we will explain the what, why, and how you can use GraphQL based on our recent experience.
GraphQL vs REST
GraphQL was developed to cope with the need of more flexibility and efficiency. It solves many of the shortcomings and inefficiencies that developers experience when interacting with REST APIs.
Let us assume a scenario where an application needs to access information on a user, his posts and his followers in a blogging database. To be more specific, the client wants to get a particular user name, all the titles of his posts, and the name of his followers, possibly limiting the amount returned.
With a typical REST API, you would gather the data by accessing multiple endpoints. Here the client first called the “users” endpoint to get the name of user “USER_001”. The second call was to the “posts” endpoint to get the titles of all posts posted by “USER_001’’, and finally a last call to the “followers” endpoint return the followers of the user (see Figure 1).
Immediately we see two major problems when dealing with a REST API:
All the three requests returned data that was not needed by the client. The user id and address, the posts content, and the followers’ id and address were returned in the rigid response, and discarded by the client. Nevertheless this was data that was transferred over the network.
The above problems raise from the inflexible nature of the typical REST API.
Now let us see the flow of the same scenario when using a typical GraphQL API. In this case (see Figure 2) we only need one endpoint. One single request is sent to the server that includes a query with the concrete data requirements. The server responds with a JSON object which represents the exact data that was specified in the query requirements. The server is responsible for parsing the query and mapping it to the backend data.
Clearly here we see the flexible nature of the GraphQL API:
Taking a closer look at the GraphQL query in our scenario, we can see from a conceptual view the following:
So far so good; but how does the client know which data can it queries from the API? This is done by the schema, which defines what objects and fields the client can query. The schema is defined by the API and exposed to the client. Objects in the schema are related to each other using the graph model, where data is organized as nodes, relationships, and properties (more on this in the next section).
From the above, we see 3 very important concepts of GraphQL:
The GraphQL Schema – a closer look
The schema is one of the most important concepts when working with a GraphQL API. It is often seen as a contract between the server and the client. It specifies the capabilities of the API and defines how clients can request the data. It defines the server API, allowing clients to know which operations can be performed by the server.
The schema is written using the GraphQL schema language (also called Schema Definition Language, SDL). With it you can define object types and fields to represent data that can be retrieved from the API as well as root types that define the group of operations that the API allows.
The root types are the entry points to the API and are split in the Query type, Mutation type, and Subscription type, which are the three types of operations that you can run on a GraphQL server. The query type is compulsory for any GraphQL schema, and the other two are optional. Although you can define custom types in the schema, the GraphQL specification also defines a set of built-in scalar types called the primitives, which are Int, Float, Boolean, String, and ID. The data in the schema is graph-modelled.
A schema for the blogging scenario mentioned above could be contextually viewed as:
Relation type between objects can be one-to-many or one-to-one. The important things to remember about the schema are:
In the scenario mentioned earlier, we used the argument “last” when in the query we were defining the followers.
The “last” argument instructs the server to only return the last 3 followers for that user. Thus the schema for our blog scenario, using the GraphQL SDL would look something like this:
Client Query examples using the schema
Here are some queries that we would be able to send to the server with the above schema:
The GraphQL Schema – a server perspective
At this point we are mostly covered from the client side with regards to the schema, but what about the server side? The client is sending queries and receiving requested data, but the server needs to do the dirty work to fetch the actual data.
The GraphQL server has 3 major components (see figure 4): The Schema, The Parser and The Resolver.
The Schema as we have already seen, defines what objects and fields the client can query. This is the contract with the user.
The Parser function is twofold:
Once the parser has called all “resolver functions” for each type, and has all the data at hand it will then build the response and send it back to the client.
The Resolver contains the functions which fetch the actual data. The sole purpose of a resolver function is to fetch the data for its field. Once all resolver functions are returned, the server will package data up in the format that was described by the query and send it back to the client.
Note that the resolver can call any interface to get the data. As shown in figure 4, it can access any database type and can even call a REST API.
GraphQL over HTTP
Figure 5 below shows how GraphQL is typically transferred over the HTTP protocol:
Note that the GraphQL query is not JSON; it looks like the shape of the JSON you want. So when we make a ‘POST’ request to send our GraphQL query to the server, it is sent as a “string” by the client.
The server gets the JSON object and extracts the query string. The server returns the data as a JSON object.
If an error occurs on the server the response will contain a list of errors the client can parse.
GraphQL @ GO
Recently at GO we wanted to bridge the link between Customer Care Agents and the CMU (Cable Maintenance Unit) Team, making the process of information sharing more efficient.
This resulted in our customer facing employees having direct visibility with regards to cables and maintenance works.
The project involved the integration between the Salesforce platform and the Monday cloud service.
Let’s have a closer look at the main differences between GraphQL and Rest:
We hope this article has given you a lot of information on how GraphQL can benefit your business and processes. The main reasons we are using this new tool can be summarised:
About the Author and the Team
Gerald Sammut is a Software Developer within the Digital Team of GO, with 30 years of experience. With his colleagues they are the wizards who focus on the fibre logical network inventory re-engineering.
Have a look at our careers page and get in touch with us if you want to take your career to the next step! For GO products and services, visit our official website or get in touch with our experts online or by visiting any of our GO outlets.