Introduction to GraphQL: A Query Language for APIs

GraphQL is an API standard that provides a more efficient, powerful, and flexible alternative to REST. It was created by Facebook in 2012, was open-sourced in 2015, and is now maintained by a large community of companies and individuals from all over the world. GraphQL is 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 in which 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 and 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 use access endpoint /users/:

To fetch all the posts of a user, we use access endpoint /users//posts:

To fetch followers per user, the endpoint is /users//followers:

With GraphQL, on the other hand, we 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 where in 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 — the name of the user, the titles of the posts by that user, and the names of the last three followers. When the server receives 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 what the response will look like:

The root field in this JSON object is called data. That's 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?

REST API Architecture

First, the client has to make three requests for three kinds of data:

1. For the user

2. For his/her posts

3. For his/her followers

Second, for every call, the server returns the unwanted data. When the client needs only the title of the user's posts, the 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.

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.

Now that we have a better understanding of the technical differences between GraphQL and REST, let's 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 involves 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, i.e. 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 and 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 the frontend and backend 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 was to introduce you to GraphQL and show you how it's better than REST. In the next blog, we will discuss the core concepts of GraphQL. So, stay tuned!

If you enjoyed this article and want to learn more about GraphQL, check out this collection of tutorials and articles on all things GraphQL.