DEV Community

loading...
Cover image for What is GraphQL?

What is GraphQL?

daliboru profile image Dalibor Belic ・3 min read

GraphQL is a query language for reading and mutating data in APIs

By the end of this, you'll understand what GraphQL is, how it works and how's it different from REST. I will also provide some resources for further research. I'll try to be concise...


Let's start by explaining how REST works. And if you're familiar, you can jump to this section,

REST

REST, or Representational State Transfer, is an architectural style for providing standards between computer systems on the web, making it easier for systems to communicate with each other. In other words, with REST, as with GraphQL, we are consuming an API. In the case of RESTful API, data entities live on various URLs on a server. When a request is received the API responds with the full data payload of that entity. Hence, there are two possible drawbacks here. First, we may need multiple entities at the same time in which case each request is under-fetching the data we want. Second, we may only want a small subset of a larger data entity in which case we need to over-fetch from the API.


GraphQL

So, we said that GraphQL is a query language for reading and mutating data in APIs. While in a RESTful API, data lives on multiple URLs on a server. In the case of GraphQL, the API has a single entry point (/graphql).

Now, let's imagine we have a team of 2, one Front End dev and one Back End dev. They are building a Koala managing website. In terms of GraphQL the perspective of the two devs, in a nutshell, looks like this:

  1. Front End Dev: Explores and requests the exact data they need (not like in the case of RESTful API)
  2. Back End Dev: Writes code to resolve that request

Back End work

Define a schema with all details needed about a Koala:

type Koala {
  id: ID!
  name: String!
  limbs: Int!
  diet: [Plant]
  fluffy: Boolean!
}
type Plant {
  id: ID!
  name: String!
  calories: Int!
}
Enter fullscreen mode Exit fullscreen mode

! - means this is required. Koala is a custom object name. ID, String, Int, Boolean are data types. We can have a custom type as well, like Plant. If we write a type inside [ ], then it's an array.

Evey GraphQL API has a Query type. It's a main entry point for a consumer of the API. getKoalas returns all Koalas, while getKoala returns a single one.

type Query {
  getKoalas: [Koala]
  getKoala(koalaId: ID!): Koala
}
Enter fullscreen mode Exit fullscreen mode

To mutate data, implement the Mutation type.

type Mutation {
  createKoala(name: String!, limbs: Int!, fluffy: Boolean!, 
    plant: { name: String!, calories: Int!}): Koala
  deleteKoala(koalaId: ID!): String
}
Enter fullscreen mode Exit fullscreen mode

Afterwards, define the code to resolve getKoalas, createKoala and others in any programming language.


Front End work

Query (fetch) data by describing it with a syntax that mirrors its return shape in JSON. Often, with React, you'd be using something like React Query or Apollo GraphQL.

In the case of Apollo GraphQL, it will look something like this:

//...

 const { data: { getKoala } = {} } = useQuery(FETCH_KOALA_QUERY, {
    variables: {
      koalaId,
    },
  });

//...
Enter fullscreen mode Exit fullscreen mode

Where FETCH_KOALA_QUERY:

import gql from 'graphql-tag';

const FETCH_POST_QUERY = gql`
  query($koalaId: ID!) {
    getKoala(koalaId: $koalaId) {
      id
      name
      diet {
        name
      }
    }
  }
`;

//...
Enter fullscreen mode Exit fullscreen mode

And this is the pattern that you'll use for the rest of the fetching part of the code.


Resources

As I tried to be concise, I'll leave you with some resource for further research. Have fun, GraphQL is awesome!

Additionally, you can check out my MERNG stack side project w/ Apollo GraphQL and TailWindCSS:
-server
-client


Thank You!

I hope you find this post useful! Any feedback is greatly appreciated!

Cheers,
Dalibor

Discussion (3)

pic
Editor guide
Collapse
nathbabs profile image
Nathaniel • Edited

So is routing, graphQL based or graphQL is just used for creating and reading data ?, Like doing "/:params" in REST, since all graphQL have to be accessed via the "/:graphql" endpoint, is it possible to convert that kind of endpoint to graphQL

Collapse
arvindpdmn profile image
Arvind Padmanabhan

Also useful to learn how to migrate from REST to GraphQL: devopedia.org/rest-api-to-graphql-...

Collapse
daliboru profile image
Dalibor Belic Author

Neat! Thank you for sharing.