GraphQL Overview: a Simple Introduction for Any Developer

GraphQL Overview: a Simple Introduction for Any Developer

GraphQL has been trending and gaining popularity over the last few years. Facebook, Shopify, Coursera, and Pinterest are just a few companies already leveraging “a new query language for APIs”.

In layman’s terms, GraphQL is a query language that describes how to request data. It is mainly used for data download from a server to a client. Being a strongly typed runtime environment, it allows you to determine what data is needed, thus avoiding problems associated with both excessive sampling and under-utilized data.

GraphQL quick facts:

  • It allows you to strictly determine what data is required.
  • It eases data aggregation from several sources.
  • It uses Type System for data description.

GraphQL is sometimes represented as a revolutionary way of API comprehension. Instead of working with strictly defined endpoints, the necessary data is received through one query. How long have you been dreaming about a smooth workflow between frontend and backend development teams? GraphQL makes this dream come true.

GraphQL: How it Works

GraphQL was introduced by Facebook, but even less complicated apps can face REST API interface constraints. Here is a simple example for you to understand how it works. Suppose you need to request posts.

GraphQL example

Now let’s complicate the task and request the number of likes and comments. Again not a big challenge.

GraphQL example 2

Let’s complicate the task. Imagine that using just one request you need to gather posts, the number of likes and user comments. The needed request will look approximately like this:

GraphQL example 3

Requesting all this data at one time will lead to a significant performance decrease. To avoid it, you need to have several endpoints. In our case, three endpoints are required, but with GraphQl you need just one endpoint to display the required data.

Now think for a moment of your Facebook news feed. Every 60 seconds active users post 293,000 statuses, upload 136,000 photos, make 510,000 comments… Can you count how many REST queries are necessary in order to display the latest posts? It’s obvious why REST API has reached its limit.

Facebook solved a problem with the infinite number of endpoints. Instead of having numerous disconnected, it’s better to have one “chief” able to work with complicated queries shaping them in the required form. GraphQL virtually stands between a client and one or several data sources. It’s like a personal assistant that brings to life various requests in one single call.  

GraphQL principle

GraphQL servers can be built on various languages, including JavaScript, Python, Java, C #, Scala, Ruby, Go, Elixir, Erlang, PHP, and Clojure. Moreover, they are not necessary to use. The main thing is to understand the approach while writing your own library from scratch. Since it is not connected to any database, it can be set up with the existing code just connecting GraphQL as a new endpoint.

GraphQL Components

GraphQL components include Schema, Queries and Resolvers. Sсhema describes all possible data that can be received. It’s strictly typitized. Note that your Graphql Schema and your database schema are not the same. It means that you can define code specific values which don't exist in your database as a field.

Key notions to understand: Character, String, String!, [Episode]!. More detailed information on how it works read here.

Now let’s have a closer look at Queries. For the following examples, we took gem 'graphql' - the library itself and gem 'graphiql-rails', group: :development for testing querying in development mode.

Here’s what GraphQL queries looks like if you just want to load all projects titles:

Querry in GraphQl

GraphQl allows you to create subrequests. For example, here we see not only projects but also user emails.

Subrequests in GraphQL

Whatever request you may create, GraphQL displays necessary data, i.e. you can make various queries but the result will always the same: the required data. Note that the GraphQL query scheme and the structure of your database are not connected.

GraphQL Querries

Resolvers is a function that determines what data to return. GraphQL gives you the freedom to determine what posts to return: a bunch of posts or posts of authorized users. Resolvers determine if we need `Posts.all` or `current_user.posts`.

GraphQL Resolvers

Now let’s cover some disadvantages. Since the technology is rapidly developing, the best practices are yet to come, so keep up with the latest trends and updates.

GraphQL is not the best decision for very complicated or nested queries. As you can see from User 1’s data on the picture below, his sites and projects with users we extract the data we already have. Here two solutions are possible: set request timeout or restrict nesting (do not upload what already has been uploaded).

GraphQL drawbacks

Using GraphQL with SQL database there can be complicated requests which are time-consuming to process. In REST architecture, we can create Joins and Groups which are impossible in GraphQL. Of сourse, there is a cache, but it’s better to upload large data amounts using NoSQL databases since it will be faster to obtain necessary data.

As seen from the examples, GraphQL helps acquire the necessary data using just one request. There is a large list of projects where GraphQL can significantly decrease the amount of code while making the architecture more flexible and reducing time on development. It eliminates creating a number of endpoints and can serve as an alternative to REST API.

GraphQL is a convenient instrument in terms of solving many issues related to interaction between frontend and backend. If you work, for example, with relational databases, then perhaps it won’t work since there might be performance issues.

If you’re curious how GraphQL can help in solving your problems, we would be happy to answer all your questions.  

Created by Tatiana Karpesh.