April 20, 2020

5 reasons that you should consider switching to GraphQL Query Language

Hello my name is Luiz and I'm a software engineer from Brazil, and today I'm going to show you 5 reasons that you should consider switching from REST to GraphQL. So without any further ado let's get started!

Solves the under fetching and the over fetching

Under Fetching: Under fetching is when you get less data than you need
Over Fetching: It's when you get more data than you need (like some fields on the JSON that you don't need), causing big performance issues because the JSON that will pass through the network it will be bigger.

How its solved

GraphQL solves this using his Graph structure for Querying data and also using the GraphQL Schema to map those fields on the GraphQL API. So let's suppose that you want to get a Star Wars character from the API and get his name, hair color, and birth year:

With rest you will do something like this:

You will make a GET request to this endpoint: https://swapi.dev/api/people/1/

That's will be your response:

{
  "name": "Luke Skywalker",
  "height": "172",
  "mass": "77",
  "hair_color": "blond",
  "skin_color": "fair",
  "eye_color": "blue",
  "birth_year": "19BBY",
  "gender": "male",
  "homeworld": "http://swapi.dev/api/planets/1/",
  "films": [
    "http://swapi.dev/api/films/1/",
    "http://swapi.dev/api/films/2/",
    "http://swapi.dev/api/films/3/",
    "http://swapi.dev/api/films/6/"
  ],
  "species": [],
  "vehicles": [
    "http://swapi.dev/api/vehicles/14/",
    "http://swapi.dev/api/vehicles/30/"
  ],
  "starships": [
    "http://swapi.dev/api/starships/12/",
    "http://swapi.dev/api/starships/22/"
  ],
  "created": "2014-12-09T13:50:51.644000Z",
  "edited": "2014-12-20T21:17:56.891000Z",
  "url": "http://swapi.dev/api/people/1/"
}

See that response is bigger than you expect you just want 3 fields, name, hair_color, and birth_year; instead you get some additional fields that you don't need.

Let's see how we do in GraphQL:

In GraphQL it's a little bit different you will make a GraphQL query with the fields that you need and send it to the GraphQL API as Post on the graphql endpoint

query GetPerson {
  person(personID: 1) {
    name
    hairColor
    birthYear
  }
}

And that will be the response to your request

{
  "person": {
    "name": "Luke Skywalker",
    "hairColor": "blond"
    "birthYear": "19BBY",
  }
}

So if you see now we have only the fields that we need, and this will reduce the response size so will be a lighter package to run through the network, and also the front end will know what the response will be like because he specified the response on the query.

How the GraphQL structure reduces the number of requests

Here we will talk about one of my biggest pains with REST. There's a huge problem with REST that is needing to make more than one request to different endpoints to return the data that you need, and GraphQL solves this problem really well.

So let's show you how it's solved with GraphQL and with REST, let's do the same request that we did on the last example, but now we want only the name and the films from that start wars character:

https://swapi.dev/api/people/1/

{
  // ...
  "homeworld": "http://swapi.dev/api/planets/1/",
  "films": [
    "http://swapi.dev/api/films/1/",
    "http://swapi.dev/api/films/2/",
    "http://swapi.dev/api/films/3/",
    "http://swapi.dev/api/films/6/"
  ],
  "species": [],
  "vehicles": [
    "http://swapi.dev/api/vehicles/14/",
    "http://swapi.dev/api/vehicles/30/"
  ],
  "starships": [
    "http://swapi.dev/api/starships/12/",
    "http://swapi.dev/api/starships/22/"
  ]
  //...
}

As you can see that above it returns to you a URL on the film's array, this is to make another request for the films and return the movie, this will be in this case new requests to return the 4 movies that the appears, but let's show you now how GraphQL solves this problem:

query PersonWithMovies {
  person(personID: 1) {
    name
    filmConnection {
      edges {
        node {
          title
        }
      }
    }
  }
}

The Response should be something like this:

{
  "name": "Luke Skywalker"
  "filmConnection": {
    "edges": [
      {
        "node": {
          "title": "A New Hope",
        }
      },
      {
        "node": {
          "title": "The Force Awakens"
        }
      },
      //...
    ]
  }
}

So see we will not need to make another 4 requests to the backend to return the movies for us. this will make the front end performance improved, and also the payload will be reduced because you will get only the title for each movie, not all the movie fields.

Adios Swagger

In rest to write the docs for the endpoints, you can use swagger but this has a huge problem because the endpoint and if the developer does not update the swagger the documentation will be outdated so the developer will need to write the code for the endpoint and for the swagger docs. On GraphQL thanks to the Schema we don’t need this because GraphQL uses a Schema first architecture so you code the API thinking in your schema fields, and GraphQL generates a schema to handle the documentation for you!

The GraphQL Clients

For rest using React for an example, you will need to use a store-management framework like Redux/Mobx to handle the state and the async middlewares to make the requests and store its results globally on the store. But on GraphQL you have the Relay/Apollo clients that will do this for you the whole store management and also the queries, store management, and also has a plus that before with REST you need to do manually if you use Typescript you can generate the typings for the query results using the relay compiler on Relay and the apollo codegen on the Apollo Client.

https://relay.dev/
https://www.apollographql.com/

The Subscriptions layer it's not separated from the queries and mutations

With GraphQL you have the same structure that you have for Queries and Mutations for Subscriptions, which are real-time socket-based connections, you can use the same structure for the Subscription Query, and in REST you will need to create a web-socket layer using socket.io with a WebSocket port open for realtime updates and also has the over fetching issue that you cant request what you want, will always return a huge payload on each update, and the web-socket will also be documented inside the GraphQL Schema! And if you use the Relay or Apollo you can generate Typescript Typings for those responses also!!

This is how you make a subscription using GraphQL:

subscription {
  watchPerson(personID: 1) {
    name
  }
}

Let's supose that someone mutated the data and sended a new event to that subscription the events returned should be like this.

{
  "person": {
    "name": "Luke Skywalker",
  }
}
// ...
{
  "person": {
    "name": "Luke Skywalker Updated",
  }
}

Here is a big example of a GraphQL project that I made with Apollo, React Native, and NodeJS: https://github.com/LFSCamargo/Chatify