What GraphQL is in 30 seconds with an example

If, like me, you’ve spent way too long wondering what GraphQL is because sentences like query language for your API makes no sense to you. This blog post is for you.

In a REST API world, you have various endpoints to get, put and delete resources, right?

Let’s say we have an app that manages a leaderboard and we have the following routes:

POST /score/:playerId
GET /score/:playerId
GET /leaderboard/:leaderboardId
PUT /leaderboard/:leaderboardId

Now, say we have 6 players that are part of a leaderboard, on initial load we want to load up the state of the leaderboard, which includes all player names and player scores.

The way we would do this using REST would be:

1 call  x GET  /leaderboard/:leaderboardId
6 calls x GET /score/:playerId

GraphQL lets us replace the 7 network calls to get only the data we need with 1 call where we define the shape of the data we want.

The request would look something like this:

1 x call to the graphql endpoint where we define what we want// The request would look something like this: - Give me the leaderboard data for leaderboardId 12345
- Give me scores for these playerIds [1543, 1845, 1943, 1375]
Importantly, we can explicitly state the data we're after, so we are not getting more data than we need for the UI i.e.- I don't care about the player score histories so don't give me that
- I don't care about when the player scores were last updated so don't give me that
- I don't care when the leaderboard was last updated, so don't give me that

One last thing to note is that GraphQL is not a framework (like say Express.js) but it is a spec (much like JSON) and can be implemented across different languages (Go, Rust, Java, C++ etc).

Hope this helps!

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