Introduction to GraphQL – A Query Language for APIs

Reading Time: 6 minutes

GraphQL is an API standard that provides a more efficient, powerful and flexible alternative to REST. It was created by Facebook in 2012 and was open-sourced in 2015 and is now maintained by a large community of companies and individuals from all over the world. GraphQL is just a specification, meaning it’s just a set of rules defined in a document.

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. It’s been in production use in Facebook’s native apps for several years.

GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

At its core, GraphQL enables declarative data fetching where a client can specify exactly what data it needs from an API. Instead of multiple endpoints that return fixed data structures, a GraphQL server only exposes a single endpoint and responds with precisely the data, a client asked for.

GraphQL is the better version of REST:

Representational state transfer (REST) or RESTful web services is a way of providing interoperability between computer systems on the Internet. REST-compliant Web services allow requesting systems to access and manipulate textual representations of Web resources using a uniform and predefined set of stateless operations. Other forms of Web service exist, which expose their own arbitrary sets of operations such as WSDL(Web Service Description Language) and SOAP(Simple Object Access Protocol).

Over the years, REST has become a standard for designing web APIs. It offers some great ideas, such as stateless servers and structured access to resources. REST itself is actually a strict specification of how a server has to expose the data to its clients. However, today almost all APIs are labeled  to be RESTful APIs even if they don’t adhere to that specification

However, REST APIs have shown to be too inflexible to keep up with the rapidly changing requirements of the clients that access them.

GraphQL was developed for more flexibility and efficiency in client server interactions, as it solves many of the shortcomings and inefficiencies that developers experience when interacting with REST APIs.

Data Fetching with REST vs GraphQL:

Let’s consider a simple example scenario of a blogging application where the application needs to display the titles of the posts of a specific user. We will analyze how it will be handled by REST and GraphQL.

With REST, we have to gather data by accessing multiple endpoints, we have to make three requests to different endpoints to fetch the required data. There is also over-fetching since the endpoints return additional information that’s not needed.

To fetch initial user data, we would have to access endpoint /users/

Screenshot from 2017-09-02 17-06-35

To fetch all the posts of a user, we would have to access endpoint /users//posts


To fetch followers per user, endpoint would be  /users//followers


With GraphQL on the other hand, we would simply send a single query to the GraphQL server that includes the concrete data requirements. The server then responds with a JSON object where these requirements are fulfilled. It works by sending a POST request to the server, wherein the body of the request, we include a query that describes all the data requirements of the client. In the below image, we can see that we are asking for a user with a particular id and then we can specify all the data we want from that user, so we want the name of the user, titles of the posts of that user and we want to have the names of the last three followers. When the server will receive this query, it will process and resolve it to fetch exactly the data that is specified in the query and read it from the database, it will then package it up into a JSON object that it just returns to the client. We can see the what the response will look like:

Screenshot from 2017-09-02 17-13-39.png

The root field in this JSON object is called data and that is what is specified in the official GraphQL specification. So exactly what we specified in the query is returned to the client

Using GraphQL, the client can specify exactly the data it needs in a query.  The structure of the server’s response follows precisely the nested structure defined in the query.

So how is communication better in GraphQL?

In REST API architecture – First, the client has to make three requests for three kinds of data. First for the user, second for his/her posts and third for his/her followers.  Second for every call server will return the unwanted data when the client needs only the title of the user’s posts server returns the content, id, and comments along with the title of the posts. This creates more data transmission between client and server and slow communication.

On the other hand in GraphQL API architecture – Only one server call will return all the required data from the server. And the returned data will contain only the required information. Hence less data transmission in just one call and eventually faster communication.

So, now we have a better understanding of the technical differences between GraphQL and REST, let’s move on to discuss a couple of high-level differences between them and see what other benefits GraphQL has compared to REST.

No more Over- and Underfetching

One of the most common problems with REST is that of over-fetching and under-fetching. This happens because the only way for a client to download data is by hitting endpoints that return fixed data structures. It’s very difficult to design the API in a way that it’s able to provide clients with their exact data needs.

Overfetching means that a client downloads more information than is actually required in the app. For example, a screen that needs to display a list of users only with their names. In a REST API, this app would usually hit the endpoint/users and receive a JSON array with user data. This response, however, might contain more info about the users that are returned, e.g. their birthdays or addresses – information that is useless for the client because it only needs to display the users’ names.

Underfetching means that a specific endpoint doesn’t provide enough of the required information. The client will have to make additional requests to fetch everything it needs. This can escalate to a situation where a client needs to first download a list of elements but then needs to make one additional request per element to fetch the required data. This is Underfetching and the n+1 request problem.

Benefits of a Schema & Type System

GraphQL uses a strong type system to define the capabilities of an API. All the types that are exposed in an API are written down in a schema using the GraphQL Schema Definition Language (SDL). This schema serves as the contract between the client and the server to define how a client can access the data.

Once the schema is defined, the teams working on frontend and backends can do their work without further communication since they both are aware of the definite structure of the data that’s sent over the network.

Frontend teams can easily test their applications by mocking the required data structures. Once the server is ready, the flip can be switched for the client apps to load the data from the actual API.

The aim of this blog is to introduce you with GraphQL, what it is and how is it better than REST. In the next blog, we will discuss core concepts of GraphQL. So, stay tuned 🙂

Please feel free to suggest or comment!



Written by 

I am a Software Consultant and has experience of more than 1.5 years. I like to study and write about latest technologies.

4 thoughts on “Introduction to GraphQL – A Query Language for APIs7 min read

  1. This all seems like a good idea if all you do all day is write code that deals with post and comments, how ever if you are building any reasonable web application, you would most likely have objects with more than 5 properties / properties,

  2. Two decades ago, I had worked extensively with integration technologies like CORBA. These had the same premise: define the schema somewhere, and let clients and servers decide how to interpret it. Then, provide a runtime layer to effect the communication in a type-safe way.

    We moved away from those, because of the complexity involved much of which was alleviated by introduction of XML and later, JSON. REST came because we wanted to treat the Server has a repository of data in a certain fashion.

    Of late, I can see that the premise made by CORBA in early 90’s, is making a comeback. I am trying to understand, why.

    The schema’s version is still to be maintained. That problem – and it can be a serious problem at times – doesn’t go away, does it? Am I missing something? Please educate me.

Comments are closed.