The fundamental differences between GraphQL and REST

A quick introduction to GraphQL

In this post, I am not going to focus on explaining what GraphQL is, instead we are going to compare how it is different from REST. But if you are new to GraphQL, here is the long story short. GraphQL is the new kid in the block and is an alternative to writing APIs using REST.

It was developed by Facebook as an internal solution for their mobile apps, and was later open sourced to the community. Ever since then, it has been widely popular among developers and has become a favorite solution for building services.

GraphQL is a query language and is agnostic of the language you use. It is just a specification. The client can query for the data they need from the server. And the server responds back with a JSON response to the query. The interesting thing to note here is that, the client can ask for exactly what they need, and they receive only that. Yes!

Isn’t that interestingly different from the REST approach? Let’s dive in and learn their differences.

1. Data Fetching

Let’s assume that we want to access the data in the programmingwithmosh.com blog. I want to build an app, that displays the blog author information. I want it to display the name of the author, the blog posts written by the author and the three most recent blog topics written by the author.

REST

In Representation State Transfer (REST), we call an endpoint, to request the data that we need. The server then responds back with the response. If we were to use REST APIs, then I would first have an endpoint that could be:

/blog/author/<id>

This endpoint would fetch the author’s information. I would then need another endpoint to access the blog posts.

/blog/author/<id>/posts

And finally I would need another endpoint to get the blog topics.

/blog/author/<id>/topics

Multiple round-trips with REST

You get the idea, this is the typical number of roundtrips that you will have to make while using REST to get the data that you need. REST endpoints get out of control, as our data needs expand. This leads to multiple round-trips, and causes a slowness in response time.

Over-fetching and Under-fetching Problems with REST

Often with REST, you will end up with data that you don’t need. For example, when calling the blog/author/<id> endpoint, you will get all the data pertaining to the author. You could get back data like, date_created, date_updated, age, gender and so on. But all we needed was the author’s name. This is a classic example of over-fetching in REST.

In the case of under-fetching, you can notice here that just the call to blog/author/<id> was not sufficient to retrieve what we are looking for. To get the last three posts written by the author, we had to make a call to another endpoint blog/author/<id>/posts. This situation is called under-fetching.

GraphQL

Guess what happens in the GraphQL world? You write one query to ask for what you want, and you get back exactly what you asked for.

There are no multiple round-trips to fetch data in GraphQL

This will make more sense if you see the actual query and the response received.

GraphQL Query Request

This is how our query will look like. We pass in the fields that we need response for. We are looking for the author’s name, last three blog posts written, and the last three topics they wrote. The query is structured to ask exactly what we need.

 {
 author (id: 6) {
   name 
   posts (last: 3) {
     title
   }
   topics (last : 3) {
    name
   }
 }
}

GraphQL Query Response

Here is what we get back from the server.

{
 "data" : {
   "author" : {
     "name" : "Adhithi Ravichandran",
     "posts" : [
       { title: "React vs. Vue : A Wholesome Comparison"},
       { title: "React Lifecycle Methods: A Deep Dive"},
       { title: "5 Essential Skills A Frontend Developer Should Possess"}
     ],
     "topics" : [
       { name: "React and Vue"},
       { name: "React"},
       { name: "General"}
     ]
   }
 }
}

We got a JSON response back from the server that has exactly what we asked for. It has returned the author name, the last three posts written by the author and the last three topics authored by author. Nothing more, nothing less and everything in a single trip to the server. Isn’t this amazing?!

GraphQL: No multiple rounds trips to server, no over-fetching and no under-fetching of data

The differences in data fetching are the biggest differences between REST and GraphQL.

2. Rapid Product Development on Frontend

While using REST APIs, client teams that are using the APIs have to wait for the backend team to complete their development of APIs, to start using them. Often, the frontend team sees slowness in development because of this prolonged waiting for APIs from the backend team. I have been a part of this situation several times, where the frontend developer’s hands are tied until the backend hands over a working version of their API.

This leads to slowness in development, and a huge reliance on the backend team to deliver faster so that the client team can start their work to consume the API.

In the GraphQL world, there is a different approach. The frontend and backend teams can develop in parallel, without stalling the development.

GraphQL: Teams work in parallel, leading to rapid product development

The frontend teams can work with mock versions of the API, and also use libraries like GraphQL Faker to create fake data. Coding can be completely done with mock data and tests can be written too. When the backend team is ready with the APIs, the mock API can be switched with the real API.

No Versioning of API in GraphQL – Non-breaking changes

With the idea that you ask for only what you need, GraphQL APIs do not need versioning. This means the changes made to the API are not breaking changes. Updates can be added to API, without affecting the client. Overall, GraphQL provides a much more pleasant experience to the developers and enables teams to work independently.

3. Community and Ecosystem

The GraphQL community has grown a lot in the last few years. The growing community interest in GraphQL has resulted in an all encompassing ecosystem with developer friendly tools. There are plenty of client and server libraries for GraphQL, making development much easier.

REST is a traditional approach, and has an established ecosystem. But REST has always been a backend developer’s forte. Whereas with GraphQL, even frontend developers have started using it to develop the APIs etc. The learning curve with using GraphQL is far less, and the developer friendly tools have led to a sizable increase in the adoption of GraphQL.

The GraphQL ecosystem has plenty of amazing tools. One of my favorite is the GraphiQL explorer. With GraphiQL, you can type your queries to the API and get responses back from the server. The documentation is also available, along with live syntax and validation errors. Tools like these, make the GraphQL developer experience far ahead of REST.

We will learn about GraphQL tools in another post at a later time. Here is a link to some awesome GraphQL tools if you are interested in exploring them.

Conclusion

REST is a traditional approach and has been around longer. GraphQL is catching up and has gained a lot of momentum. Don’t think GraphQL is an option only for new products and new code. Even if you are working on legacy systems that use REST, you can still integrate GraphQL to fetch data from the legacy REST systems. This would help in improving the client layer. You can write queries to the new GraphQL server, which then talks to the legacy systems.

If you are already using GraphQL, leave a comment on what strikes you the most about it.

Thanks for reading ❤

If you liked this post, share it with all of your programming buddies!