GraphQL - A brief introduction

At a first glance, GraphQL can seem quite intimidating. There's plenty of information out there about it, but a lot of it is pretty cryptic (it's even hard to get a base line definition of what it is).

I've recently spent some time breaking it down into more digestible chunks - here are my findings.

It all starts with an API

It's impossible to talk about GraphQL without talking about APIs. If you're new to programming, this is for you. Otherwise skip this section.

MuleSoft have a great video talking about APIs and they use the following metaphor:

An API is the messenger that takes your request and tells the system what you want to do, and then returns the response back to you. Think of an API as a waiter in a restaurant. Imagine you’re sitting at the table with a menu of choices in front of you, and there’s a kitchen that will prepare your request for you.

What’s missing is the critical link to communicate your order to the kitchen, and deliver your food back to your table. That’s where the waiter, or API, comes in. The waiter is the messenger that takes your request and tells the system, in this case the kitchen, what to do. And then delivers the response back to you, in this case food.

What is it?

Now we're familiar with APIs, it will make a bit more sense when I say that GraphQL is a query language for APIs.

Query languages are used to get data - you'll probably already know of SQL, that's another query language (it lets us access data from a database). GraphQL doesn't work with databases, but instead it lets us access data from an API.

Why not REST?

To get to grips with why it's useful, it makes sense to consider the problems that fuelled its development.

REST architecture (Representational State Transfer), was developed in the 90s as a way to improve the efficiency go comms systems. It let us transfer XML or JSON data and gained popularity super quickly.

As the applications it was used for gained complexity, the more problems started appearing.

• Firstly, with REST, different resources are fetched from different endpoints. This means that when there is a need for a lot of different information, there'll be A LOT of endpoints. This can make our code messy, repetitive, and difficult to maintain.

• With this came the problem of over and under-fetching. Over-fetching is when you fetch too much data and then don't use all of it. Under-fetching is when your fetch doesn't return all of the data you need, so you have to make another fetch request.

GraphQL was designed to eliminate those problems. It's done a pretty good job of it and is now commonly used by companies that handle large data and need to have access to complex data structures - companies like Facebook, Netflix, AirBnB, and Twitter.

The fundamentals

When making an application with GraphQl, there are two parts to consider, the client and the server.

GraphQL exists as a layer between the two. The client side will render the UI and in doing so, will use GraphQL to request data from an API. GraphQl then decides what to return.

Requesting data is called a query and its like a HTTP GET request. Requesting to update or change the data is a mutation, and its like a POST / PATCH / DELETE request.

The server receives requests from the client and either fetches and returns the data from a query, or makes some changes to the data and returns it as a result of a mutation request.

And that's essentially it. Of course there are a million ways to make this more complicated, but this is a basic outline of how it works.

Apollo? Relay?

If you google anything to do with GraphQL, you'll usually find yourself somewhere in the Apollo docs. In fact, a lot of the time you'll probably find the Apollo docs more informative than the GraphQL ones, but that's a complaint for another time. Let's talk a little bit about Apollo.

As well as being a query language, GraphQL is a specification, it describes one way of accessing data over the internet. You have to write a different sort of GraphQL code on the client than on the server and a lot of developers find this annoying. So, there are libraries like Apollo, that implement the GraphQL standard to write both client and server side code.

Apollo is an implementation of the GraphQL specification. It comes bundled with Apollo Server, Apollo Client and a bunch of useful modules.

There are other implementations of GraphQL too. Relay, like GraphQL, was developed by Facebook. Implementations such as Relay and Apollo provide great additional features, but it's a good idea to get to grips with the basics before using a library.

Fin.

I hope this has been helpful! In my next post, I'll talk about the basic building blocks of GraphQL - schemas, types, resolvers and so on.