GraphQL Will Do To REST What JSON Did To XML

Roy Derks
Roy Derks
Jun 15, 2018 · 5 min read

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
  • GET
  • GET

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 to receive details for the cult movie ‘Fight Club’.

Assuming I only want to show the , and 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 and more fields are returned that we probably wouldn’t use.

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

The 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 , , , cast (, ) and reviews () for the movie ‘Fight Club’ this would translate to the following in GraphQL:

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

Hackteam

All about Development and Hackathons

Roy Derks

Written by

Roy Derks

Promoting Full-Stack JavaScript with #javascriptEverywhere. Also loves #reactjs and #ReactNative. CTO and Technical Founder of SwitchBay.com

Hackteam

Hackteam

All about Development and Hackathons

More From Medium

Related reads

Related reads

A Case for GraphQL

594

Related reads

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade