When it comes to network requests between a client and a server application, REST (which stands for Representational state transfer) is one of the most popular choices for connecting the two. In the world of REST APIs, everything revolves around the idea of having resources as accessible URLs. We then use CRUD operations (Create, Read, Update, Delete), which are basically HTTP methods such as GET, POST, PUT & DELETE, to interact with the data.

Here is an example of a typical REST request:

The response format for a REST API is not necessarily JSON, but this is the preferred method these days with most APIs. Apart from REST, another way to handle network requests has emerged: GraphQL. Open sourced in 2015, GraphQL is changing the way developers write an API on the server side and handle it on the client side. GraphQL was developed and is actively maintained by Facebook.

Shortcomings of REST

GraphQL is a query language to develop an API. In contrast to REST, which is an architecture or ‘a way of doing things’, graphQL was developed with a concept in mind that a client requests only the desired set of items from the server in a single request.

In REST architecture or like on our above example, when fetching the films Luke Skywalker appeared in in Star Wars movies, we are getting an array of films or the name of homeworld which further consists different API URLs that lead us to details of different sets of JSON data. This is certainly an example of over fetching. The client side, in order to get the details of films in which the character Luke Skywalker appeared, and the name of his home planet, will have to send multiple requests to the server.

With GraphQL, this can be resolved into a single network request. Hop on to the API url: https://graphql.github.io/swapi-graphql/ and see run the following query.

Note: In the example below, you can ignore how the GraphQL API is working behind the scenes. I will be walking you step by step to build your own (maybe the first) GraphQL API later in this tutorial.

We are going to fetch the data that we need such as the name of the character, their gender , homeworld , and the title of the films they appeared. After running the above query, you will get the following result:

If the client side of an application is triggering the above GraphQL URL, it will only send one request on the network to get the desired result, thus eliminating any possibility of over fetching or sending multiple requests.

Pre-requisites

To follow this tutorial, all you need is Nodejs and npm installed on your local machine.

Nodejs ^8.12.0

npm ^6.4.1

GraphQL in a nutshell

In a nutshell, GraphQL is a syntax that elucidates how to ask for data and is generally used to retrieve data (aka, a query) or make changes to it (aka mutation) from a server to a client.

GraphQL has few defining characteristics:

It lets the client specify exactly what data it needs. This is also known as declarative data fetching.

It is not opinionated about the network layer

It makes easier to combine several sets of data from multiple sources

It uses a strongly typed system when declaring the structure of data in the form of both the schema and the query. This helps to validate the queries even before the network requests are sent.

Building Blocks of a GraphQL API

A GraphQL API has four building blocks:

schema

query

mutations

resolvers

Schema is defined at the server in the form of objects. Each object corresponds to data types such that they can be queried upon. For example:

The schema above defines the shape of a user object with a required field id denoted by the ! sign. Other fields such as the name which is of type string and age which is of type integer are also included. This also validates the schema when querying for the data.

Queries are what you use to make a request to a GraphQL API. For instance, in our example above, when we are fetching the data related to a Star Wars character. Let us simplify this. To query in GraphQL, it is about asking for specific fields on objects. For example, using the same API as we did above, we fetch the name of all the characters in Star Wars. Below you can see the difference. On left-hand side of the image, is the query and on the right-hand side is the image.