Published in


GraphQL Will Do To REST What JSON Did To XML

If you are developing applications, either on the backend or frontend side, you should know what a REST API is and must have heard about GraphQL at any point. The first is a no-brainer for any developer and the latter is spreading quickly among developers that want to be on the forefront of new technologies, after Facebook open-sourced it in 2015.

Haven’t heard of it yet..?

In this article I won’t explain in detail what GraphQL is and how you could best use it (you could find this here or here), instead I will outline its pro’s and con’s against using REST services with a real-life example.

What’s wrong with REST?

Just to be clear: nothing is “wrong” with REST. But as it’s around for a long time already, it has been caught up by newer technologies. If I have to name the biggest problem of REST, it would be its nature of having multiple endpoints instead of just one as we have with GraphQL.

REST APIs are most of the time a collection of endpoints, with each endpoint representing a specific resource. When a client wants to access more than one resource at a time, it requires them to make multiple round-trips to the server to retrieve the data they need.

Also, clients usually have no control over the fields that are returned by an endpoint. The REST API returns all fields that are specified for this endpoint, no matter which content the client has requested — unless you have developed a client request language yourself.

Why should I use GraphQL?

As mentioned before the main advantage of GraphQL over REST services is its ability to send the requested data over just one endpoint. Not only can multiple resources be combined into one output, clients also have control over the fields that are returned.

This is especially useful to Frontend Developers as it takes away a lot complexity in handling data when constructing for example an UI view. This enables them to focus on building applications, rather than spend their time figuring out how to combine endpoints into readable data that can be displayed to the user.

Another advantage of GraphQL is its approach to versioning. With a REST API we would need to add a version parameter to the endpoint in order to make sure the correct data is returned as the API grows. With GraphQL you can just add new fields without having to delete old fields that are no longer used by newer versions of your applications.

Let’s show an Example

Suppose we would have the following endpoints for a REST API, which I (as movie buff) took from The Movie Database API:

  • GET /movie/:movieId
  • GET /movie/:movieId/credits
  • GET /movie/:movieId/reviews

The first endpoint will show us all records for a movie, the second and third endpoint will return specific details for this resource. Have a look at the JSON output from my request to /movie/:movieId to receive details for the cult movie ‘Fight Club’.

// The return for /movies/:movieId
"adult": false,
"backdrop_path": "/fCayJrkfRaCRCTh8GqN30f8oyQF.jpg",
"belongs_to_collection": null,
"budget": 63000000,
"genres": [ ... ],
"homepage": "",
"id": 550,
"imdb_id": "tt0137523",
"original_language": "en",
"original_title": "Fight Club",
"overview": "...",
"popularity": 0.5,
"poster_path": null,
"production_companies": [ ... ],
"production_countries": [ ... ],
"status": "Released",
"tagline": "...",
"title": "Fight Club",
"video": false,
"vote_average": 7.8,
"vote_count": 3439

Assuming I only want to show the title, vote_average and vote_count for this movie, we would waste a lot of network and memory resources with the request — both for the client and the server. And this is only for the first endpoint, if we look at the output for /movies/:movieId/credits and /movies/:movieId/reviews more fields are returned that we probably wouldn’t use.

// The return for /movies/:movieId/credits
"id": 550,
"cast": [
"cast_id": 4,
"character": "The Narrator",
"credit_id": "52fe4250c3a36847f80149f3",
"gender": 2,
"id": 819,
"name": "Edward Norton",
"order": 0,
"profile_path": "/eIkFHNlfretLS1spAcIoihKUS62.jpg"
}, { ... }
"crew": [ ... ]
// The return for /movies/:movieId/reviews
"id": 550,
"page": 1,
"results": [
"author": "Goddard",
"content": "...",
"id": "5b1c13b9c3a36848f2026384",
"url": "..."
"total_pages": 1,
"total_results": 1

So as a Frontend Developer that wants to show details about a movie — including its cast and reviews — I would have to make a request to three endpoints to retrieve this data. Also, I have absolutely no control about which data I receive from these endpoints. So not only would I have to make requests to these three endpoints, I also need to filter out the fields we really need before my application can show this data to the user.

With GraphQL we call this problem over-fetching of information that we don’t need. In general, a GraphQL endpoint would look something like this:

  • GET /graphql?query={ ... }

The query part will just be a string containing all the fields or the information that we need from the endpoint. As we want to retrieve the title, vote_average, vote_count, cast (name, character) and reviews (total_results) for the movie ‘Fight Club’ this would translate to the following in GraphQL:

// GraphQL query for 'Fight Club', movieId = 550
movie(movieId: 550) {
credits {
cast {
reviews {

This query almost exactly represents the output of the endpoint GraphQL returns to us — except the values of course — which contains just the information we want to display in our Frontend application. And although this is just a fictional design, it shows the advantages that GraphQL would have over REST using a real-life example.

Will REST be send to the graveyard by GraphQL?

No. Developers should use the right “tool” for the right “job”, meaning that REST principles will still be used for at least the coming years. Although the sound of having only one endpoint in GraphQL seems like heaven, it can still be over flooded by too complex queries. Also, it is yet another technology developers would have to master. But in the end, XML was (or in some cases still is) used to parse data — although it’s better suited to handle documents — while JSON is far better at handling data.

My talk at React Native EU 2018 about GraphQL

Do you like this post or have any suggestions? Please let me know! Below this post, on Twitter or by email.

Make sure to follow me on Twitter to keep notified of all things related to #javacript and #javascriptEverywhere




All about Development and Hackathons

Recommended from Medium


OAuth explained with real life example.

Python: The difference between knowing and understanding it

Gathering all Asana’s talents in one place: productivity-experts.com

Enabling Digital Transformation via Low Code Platforms

An Introduction to the Akamai Content Delivery Network

Securing Kubernetes according to the NSA

Offshore Software Development Guide [2020] | Fireart Studio

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Roy Derks

Roy Derks

Roy Derks is a serial startup CTO, developer, author and conference speaker from Amsterdam. Currently leading the engineering teams at Vandebron.

More from Medium

TypeScript-based caching decorators

The trade-off between query performance & data consistency when working with connected data in…

GraphQL beginner notes — Day 1

Connection Pooling in Database