Comparing GraphQL and REST API: Unveiling the Differences

 

There is no better ways to understand the difference between two things but by looking into a practical example and that's what you'll see here. 

The example talk about a Blog API, where we have three entities Blogpost, Author and Comments. A Blogpost is written by an Author and it can have one or more comments. If you have to build a REST API to distribute this data then you will start by creating several endpoints for different entities like 

• /post/{id} to retrieve a post by id which will return details of a blog post like id, title, content and id of author
• /comment/{id} to retrieve a particular comment by id
• /author/{id} to retrieve an author by id which will return details of an author like id, name, and its email
• /posts to retrieve all posts

Now, this architecture seems fine on theory but if you start using it for practical purpose it will show you the problems REST API faces. For example, if you want to build a feed of blog posts by displaying the title of the all blog posts and name of the author then you need to make several requests to the server. 

For example you will need to first send an HTTP request to get all posts using /posts endpoint then you need to get the author name by sending another request to /author/{id} endpoint. 

I agree that its a trivial example but it does pinpoint the problems REST API faces like you need to send a lot of request to get the data you want, which is not only make your application slow because every request to server increases response time but also increase the cost of fetching the data, particularly if you are creating a Mobile app which uses Internet data.

Now, you may argue that why not create another end-point like post_with_authors which can provide all the data you are looking, well that's what many people do but it just mask the problem. It's Ok for this case but what if you need posts with comments details as well, will you create another end-point? If yes, then this will lead to explosion of endpoints which is very hard to maintain, hence not scalable at all. 

Thankfully GraphQL solves all this problem by allowing you to get all the data you need in just one request. With GraphQL, you specify a query which is nothing but the structure of your response. For example, to get the post and author detail you can specify a query like below:

1. Single Endpoint vs Multiple Endpoints

The first and most important difference between GraphQL and REST is that unlike REST which has separate endpoints for getting different set of data, GraphQL provides just one end point to fetch the data you need. 

For example, in the Blogpost API example above, you need to send multiple request to different endpoints to get both post and author data but with GraphQL you got the data by connecting to just one endpoint. 

You may not realize now, but this is a huge advantage in terms of managing and maintaining those end points for a medium to large web application.

2. Data Download (Over fetching and Under fetching)

One of the main problem with REST is that you are either over fetching or under-fetching the data. There is no way for you to download the exact data you want, for example, if you want to download a user's name, age, and city then you just can't download that without downloading the full user object, unless you have a separate endpoint for that. 

Adding a new endpoint may work for one case but you just cannot have endpoints for every single requirement, that would lead to explosion of end-points which would be both difficult to understand and maintain. 

This problem is solved by GraphQL because you specify what exactly you need in form of a Graph query, which means you'll never download too less or too much, instead just right. 

3. Response structure

One of the problem with REST API is that you never 100% sure you what you are getting, I mean you may get more attributes or link to additional endpoints. With GraphQL you know the structure of response well in advance because it exactly matches with the query structure but with REST API, that's not always the case. You may receive an attribute which you even don't know about it. 

4. Relationship

Another important difference between REST and GraphQL is that GraphQL automatically handles relationship for you. For example, if you request for blog post which has comments then GraphQL will also fetch comments details if you have specified that in your query for you. With REST, you need to send another request to fetch data by following the endpoint provided to you.

5. Performance

One of the biggest difference between REST and GraphQL API is the immediate performance gain you get when you switch because of the architecture. We also get the exact data we need which means less memory and less parsing headache.