Introduction to GraphQL

It’s been quite a while, we have been creating REST APIs in our day to day development and everything is going perfectly fine with it. But in recent times, we have been hearing about a term, “GraphQL”. When I first heard about it, I thought it must be some querying language for the graph databases. After searching about it, I came across few videos on YouTube with some catchy titles like, “Are the days of REST APIs are gone?”. I know you must be wondering what this GraphQL fuss is all about and what will happen to our beloved REST APIs. So, let’s find out !!

What is GraphQL?

It is an open-source data query and manipulation language for APIs. It was initially developed by Facebook as an internal project in 2012 and later released publicly in 2015.

History of GraphQL

As mentioned earlier, it was initially developed as an internal project by Facebook. Everything was working fine till Facebook found itself entangled in a major issue. Both its mobile apps, i.e. IOS and Android, started sufferring frequent crashes, latency over network and poor performance as they became more and more complex. They identified that these issues were forecoming due to the limitations of REST APIs namely, over-fetching, under-fetching, numerous endpoints, too many round trips of API calls and many more. As a result, GraphQL came into existence to solve these issues.

Analogy

GraphQL is a very innovative project that gives a single “smart” endpoint instead of multiple “dumb” REST endpoints and hence, overcomes the limitations of REST architecture.

To understand the core idea, let’s take an analogy of a restaurant. It’s a special kind of restaurant where there are various kind of “Thaalis” like North-Indian thaali, South-Indian thaali, etc. The dishes are fixed in each thaali and you can’t add/remove any dish from it. There’s a waiter on behalf of the restaurant to whom you will give the order and he will bring you the ordered thaali(s). Consider the restaurant as a Web service (Employee Service), thaali as a resource (employee), each dish in that thaali as a field of that resource (empId, name, designation, age, salary) and waiter as an API. This is what REST for us. We give an order of a thaali (resource) to the waiter (API) which in turn brings the thaali to us. We might not want all the dishes of that thaali and hence, wouldn’t eat all of them (over-fetching). Another case might be like we want to taste few dishes of some other thaali but didn’t get them in the currently ordered thaali and hence, we had to order a separate one for that (Under-fetching).

Now, take an example of another restaurant which have a buffet system. They still have a waiter which will take your order. You can order and cherry pick only those dishes that you want to eat. Waiter will add only those dishes in your thaali and bring back to you. This is what GraphQL is !!

GraphQL vs REST

Now, you must have got a basic idea of what GraphQL is and why it is being considered as an alternative for REST. So, lets now discuss the differences between them.

1. GraphQL is a data query and manipulation language for APIs whereas REST is an architectural style that defines a set of constraints for creating Web services.
2. GraphQL follows client-driven architecture whereas REST follows server-driven architecture.
3. GraphQL has a single “smart” API endpoint using which client can fetch multiple data objects in a single call and can even specify the specific fields that needs to be fetched. On the other hand, REST has multiple “dumb” endpoints. Client might want only few fields of a resource but will still get all the fields of it (over-fetching). Also, he might need to call various endpoints to fetch multiple resources (under-fetching).
4. GraphQL considers data objects as nodes of graph and the edges as relationships among them (hence, the name GraphQL) whereas REST considers them as resources and exposes separate endpoint for each.
5. Error management and debugging is easier in REST as we have well defined status codes for each case and we can easily identify the status of response by examining it whereas we always receive a 200 OK status code in case of GraphQL.
6. GraphQL has only a single endpoint of POST method whereas REST has multiple methods like POST, PUT, GET, DELETE for the endpoints.
7. GraphQL allows us to make multiple queries in a single call whereas REST requires us to make different API calls if we want to fetch different resources and hence, requires numerous round trips.

Basic components of GraphQL

There are 3 basic components of GraphQL:

1. Schema

It is the core building block of GraphQL server implementation. It defines the nodes of your data graph and their relationships among them. It also specifies the queries and mutatons available for the clients in order to fetch/manipulate the data.

type Query {
  bookById(id: ID): Book 
}
type Mutation {
  addBook(name: String, pageCount: Int): Book 
}
type Book {
  id: ID
  name: String
  pageCount: Int
  author: Author
}

type Author {
  id: ID
  firstName: String
  lastName: String
}

2. Query

It is a data request made by the client to a GraphQL server. The latter interprets, executes and finally returns a JSON data back to the client. It is always a POST request and the status of response is 200 OK every time.

{
  bookById(id: 1) 
  {
    name, 
    author {
      firstName
  }
}

The response will be:

{
  "data": {
    "bookById": {
        "name": "2020 Revolution",
        "author": {
           "firstName": "Chetan"
        }   
     }
  }
}

3. Mutation

It is a request made by the client to the GraphQL server similar to a query but instead of fetching, it is used to create, update or delete the data. It is always a POST request and the status of response is 200 OK every time.

{
  addBook(name: "The power of your subconscious mind", pageCount: 256) 
  {
    id
  }
}

The response will be:

{
  "data": {
    "addBook": {
        "id": "2"
     }
  }
}

Conclusion

So, are the days of REST are gone? Hell No. GraphQL is designed for a specific use case and if it doesn’t suits you, REST is still there. You might go for GraphQL if your endpoints are becoming numerous and unmanageable and you are facing reduced performance issues due to over-fetching and under-fetching.

This was just the tip of the iceberg of the world of GraphQL but I hope it gave you a detailed overview to start off with.

My aim is just to give you an introduction to GraphQL, REST is upto you :p