GraphQL in Plain English

Giuseppe
Giuseppe
Jun 15, 2020 · 4 min read

A simple explanation of APIs, REST, and GraphQL.

Photo by Author

GraphQL is an open-source data query language for creating APIs. Built internally by Facebook in 2012 it was later made public in 2015.

Since its launch, GraphQL has attracted a lot of attention and continues to see steady growth.

To understand what GraphQL is and why it’s useful, we need to first understand what an API is and how they are typically implemented.

What is an API?

APIs are deeply connected with many aspects of our lives. Every time we check social media or search something on google we are interacting with an API.

It all happens behind the scenes.

Let’s take youtube as an example. When you type ‘youtube.com’ into your browser a request is made to Google’s servers. Something like:
“Hello Google, could I please view your website. I’m not a robot I promise.”

Google’s servers process the request and formulate a response. In this case, the response is to send back code which your browser can translate into what you recognise as youtube.com.

If you try to visit ‘youtube.com/fake-url’ you will see a message which tells you that the page you were looking for cannot be found. This is because Googles server did not know how to handle your request.

Screenshot of 404 Error from YouTube

The part of the server that receives requests and sends out responses is what we call an API. APIs can be created to fulfil any task we need, from publishing a medium article to searching for cute cat videos.

How are APIs usually created?

The majority of APIs use a RESTful architecture in combination with HTTP methods. In a RESTful architecture, every resource is associated with a URI.

Making a request to a given URI will invoke a response. Responses will vary depending on which resource was requested and what HTTP verb was used.

To demonstrate, let’s imagine we are creating an API for Todo objects. This is how our URI resource collection might look:

Table to show URI Collection for a Todo API.

The more resources we make available through our API the larger the URI collection becomes.

An important characteristic of RESTful APIs is that the client ( your browser ) does not know in advance how the data will be returned. It is through documentation and some manual experimentation that we discover how to handle the response.

Imagine one day you decide to change the implementation of your API from returning a list of Todo objects to a HashMap of Todo objects. With one seemingly minor change, you will have broken all applications that use your API.

This idea of knowing in advance how the data will look is a core feature of GraphQL. Let’s take a look at how we might implement the Todo-API using GraphQL.

How are APIs created with GraphQL?

Step 1. Define the data
GraphQL uses a language-agnostic type system to describe the shape and nature of the data. The most basic type in GraphQL is the Object Type.

We can use the Object Type to represent our Todo object like so:

type Todo {
name: String
completed: Boolean
}

Object types may specify one or many fields. In this example, both name and completed are fields and they are of type String and Boolean respectively.

Step 2. Define what requests can be made
Requests to a GraphQL API may take one of two forms.

The first is a query. Queries can be thought of in a similar way to making a GET request to a resource URI when using a RESTful architecture. They are used when we want to retrieve data.

type Query {
todos: [Todo]
}

The above query is titled todos . It returns a list of Todo object types.

The second type of request is a mutation. Mutations are used when we want to create, update, or delete some data.

type Mutation {
createTodo(name: String, completed: Boolean): Todo
}

The above mutation is titled createTodo . It takes two parameters, a name and a completed status. It returns the newly created Todo object.

Combining the data types, queries, and mutations form a GraphQL schema.

Making a request to a GraphQL API

Unlike RESTful APIs, the HTTP verb does not change depending on the type of request we are making. Instead, the POST verb is used for all requests.

Furthermore, we do not need to change the URI to accommodate the resource we are requesting.

Already this is simpler, wouldn’t you agree? Only one verb and one URI to remember.

Here’s how we would query all of the Todo objects.

query todos {
todos {
id
name
completed
}
}

Notice the three fields id , name , and completed . These are the fields that are included in the response from the API. Not only can we gauge how the data will look but we can intentionally alter its shape to suit our needs.

Suppose we only wanted the id? Or the name and id? No problem. We can change the query to suit our needs.

query todos {
todos {
id
}
}

Now that’s really cool if you ask me.

Where to go from here?

If you found this interesting and would like to delve a little deeper, I recommend you to try and integrate GraphQL into your own API.

Here’s a 10-minute guide to help get you started.

The Dev Café

Code. Learn. Share.

Sign up for Top Stories

By The Dev Café

A newsletter that delivers The Dev Café's most popular stories to your inbox once a week. Take a look.

By signing up, you will create a Medium account if you don’t already have one. Review our Privacy Policy for more information about our privacy practices.

Check your inbox
Medium sent you an email at to complete your subscription.

Giuseppe

Written by

Giuseppe

I share code and explain technical concepts.

The Dev Café

Code. Learn. Share.

Giuseppe

Written by

Giuseppe

I share code and explain technical concepts.

The Dev Café

Code. Learn. Share.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

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