Introduction to GraphQL – A New Way of Querying Data from Servers

At a high level GraphQL is a query language, that can be used anywhere but mostly being used between client and server applications to exchange the data.To understand GraphQL we first need to know what are APIs and more specifically REST APIs?

What is REST?

In general, an API (Application Programming Interface) is a technique by which we can provide an interface between two systems for the interaction. It works like a cog between two systems, that facilitate the interaction programmatically.

“It revolves around resource where every component is a resource and a resource are accessed by a common interface using HTTP standard methods.”

When we look at the request for the REST API, there are mainly two parts of it. The first is the verb or method that specifies what action needs to be taken on the resource and second is an endpoint which tells a specific part of the API we want to interact with.

Is REST helpful in modern applications?

While REST is a standard for designing and developing APIs for modern web applications, it does not always fit in the requirements. Let’s dig into the example to understand this better. Below JSON could be a response from an API like HTTP GET

(img src: https://restfulapi.net/hateoas/)

In this response there are various fields which are related to Department resources like name and ID. Along with that to get the details of employees of that department, there is a link section which provide a Hyperlink to the API to get the employees list of that department. If we execute this request, we will get Employee resource and along with that there might be some other hypermedia links.

If we are building a Desktop or a web application, we’ll end up calling multiple APIs to determine the information we need as a client. This becomes more painful when we are working with a say mobile client where the connection is super slow.

 The problem of calling multiple HTTP services to get the desired response is called as over fetching, and this has become the bottleneck for clients using REST APIs, whereas they are optimised around servers, and the resources they return.

If we take a closer look, we can see that UI developers are actually spending less than 1/3rd of their time in building UI, whereas rest of the time is being spent on how and where to fetch data and how to map that in UI objects, because of this nice UI becomes the second thought.

GraphQL

"GraphQL is a query language designed to build client applications by providing an intuitive and flexible syntax and system for describing their data requirements and interactions". - GraphQL Specification

 Image source (graphql.org)

 GraphQL is an open source query language developed by Facebook, and they are using it since 2012, as an alternative to common REST based architecture.

It allow users to request more specific data, so that they have better control over information that needs to be retrieved, in contrast to REST where the complete the complete information of a resource if provided by REST even if a part of it is needed by the client.

If we look at the picture above it shows that when we send a GrpahQL query from a client (Desktop / Mobile) to a GraphQL server, we specify what all fields do we need from the server in order to fulfil the requirements, like for a particular department we need list of employee names along with their IDs. As a response GraphQL server provide us the data, that was required.

We can clearly see the difference here, as in only single call we are getting the data that was required for the UI, we don’t have to make multiple requests and we are not getting the data that we don’t require.

With GraphQL we have following advantages over REST

 Performance

We only get the data we asked for. So, no multiple round trips to get the desired results, that provides less network calls thus better performance.

Flexibility

As a client we have more flexibility to define the structure of data, rather than depending on the server.

Developer Productivity

As a UI developer you don’t have to worry about the structure of data returned from the server and how to map that in local objects. You define your own structure and get the data from server in that particular structure only. So, more time for fancy UI. 

While there are advantages of GraphQL there are several disadvantages as well.

• Lack of built in caching support
• Difficulties in error handling, as GraphQL queries always return HTTP status code of 200, even if the query was not successful. If the query was not successful, then the JSON response will have top level key as “errors”.

REST API to GraphQL

While GraphQL has some of the limitations it certainly has lot of advantages that makes it significant to move REST APIs to GraphQL. To garner the benefits of GraphQL one must think in terms of graphs rather than end points.

 The migration can be a one-step solution for smaller applications where there are a few end points, but for bigger applications it happens gradually where both of the options work together. This is also important because the clients of the bigger applications are not expected to migrate to the new versions soon.

 In the below picture we can see that both of the options are co-existing for client, so its up to them which one they want to opt.

GraphQL Vs REST

GraphQL is an exciting new technology, but before planning the architectural pattern based on this, we need to understand the tradeoffs between REST and GraphQL. The APIs which have very limited number of relationships like Analytics APIs may not be a best fit for GraphQL, whereas applications like e-commerce and ERP can leverage the GraphQL much more due to having different domain objects and their relationships.

Industry wide adoption

GraphQL specification was given by Facebook, along with its JavaScript implementation, but there are various organisations those are spending efforts in building GraphQL ecosystem to fulfil the need of modern applications. Along with Facebook and Instagram there are following well-known companies which are using GraphQL

• Shopify
• Twitter
• PayPal
• GitHub
• The New York Times