A beginner's guide to GraphQL

SO, what is GraphQL? GraphQL is basically a query language for fetching and manipulating data from a backend server. It is called GraphQL because data can have mutual connections and they can be linked using a graph-like structure. Unlike REST APIs, GraphQL do not return some fixed data from a resource. If you don’t know about REST APIs, you can read one of my posts on REST APIs here.

But in a nutshell, REST APIs are about having one specific endpoint for one resource and they return a fixed data structure. While REST APIs are unarguably the most popular way of fetching data from a backend server, it turns out they might not be ideal in scenarios where we want specific data and not the entire dataset. May be one scenario asks for only 2 fields from the dataset, say name and email of a user. In other scenario, we want 3 fields like name, email and date of birth. Such an objective cannot be achieved with REST APIs because they are designed to return fixed data structure as response.

And GraphQL to the rescue 🦹 We can fetch only those fields which are required at the moment using GraphQL by writing structured queries which specify what we are looking for to the server and server returns only those values from the dataset.

Let me try to bring out the contrast between GraphQL and REST APIs using a real-world example. Consider the office scenario where there is a well-established hierarchy. There is a department, each department has multiple projects going on and there is one head of department. Each project is being worked on by multiple employees. Now, the admin wants some information of a particular project running in a specific department. So he wants to know department name, head of department, project name, deadline, project manager, how many employees are working on the project, their names and experience.

If we try this with REST APIs, we need to make use of minimum three REST endpoints which can look something like this -

/api/department/{id} - for knowing department name and head of department
/api/project/{id} - for knowing project name, progress, deadline, number of employees working on this project
/api/employee/{id} - for knowing employee name and his/her experience

In fact, we will have to make N number of requests to the third endpoint if there are N number of employees working on a project because we want details of each employee. So, the total number of requests to the server will be - 1+1+N. Because N is variable, so number of server requests will increase as we increase the value of N, which might be a concern if N grows to be sufficiently big. Although there might be work-arounds for this, but here's another concern - Response from each API endpoint is likely to give us all the information present in the database about that resource. We might get all the data of that department, project or employee we are requesting for, but as mentioned above, we need only certain pieces of information. This results in redundant data, also called "over-fetching" information.

And GraphQL has a really good solution for both the setbacks. Using GraphQL, we need only one endpoint (and only one request) and we will get exactly the information we are looking for. Neither more nor less.

GraphQL is all about writing schema and then queries. In schema, we specify the structure of the query and query is where we ask for the data. I will make a blog post or video on writing schema and queries in GraphQL but for now, let's stick with the theoretical part only for explanation. We can make a GraphQL endpoint and write a query something like this -

{
    query{
        department{
            departmentName
            headOfDepartment
            project{
                projectName
                projectManager
                deadline
                employees{
                    employeeName
                    experience
                }
            }
        }
    }
}

Actually the thing is, in GraphQL, resources are interconnected and it's like a maze where GraphQL can navigate and pick-up only the requested data fields and return the response. These relationships among the resources are specified on the GraphQL schema.

So, this was just a theoretical explanation of GraphQL. If you wish to understand GraphQL in more detail, I have also made a video tutorial on GraphQL where we will be making a small superhero GraphQL API using apollo-graphQL, NodeJS and TypeScript. If you want to get a hands-on experience of GraphQL, you can check this out.

So basically, GraphQL is a great way of fulfilling the shortcomings of REST APIs. In any scenario where you want "selective" data, GraphQL can be your go-to option. See you soon in a next post 🙋‍♂️