GraphQL - Beginner's Guide

Danish Shah   |  12th September, 2019

To understand what GraphQL is we need to understand why GraphQL was created.

| Before you go any further. This blogpost is aimed at all the beginners like me to get familiar with some very basic terminologies of GraphQL. Enjoy!

| A Bit of History

GraphQL was created by Facebook in 2012 and open-sourced later in 2015.

The systematic industrial shift from desktop, computer, and browsers towards mobile demanded some technical level architectural change as well. This made Facebook rethink its mobile strategy of how to adopt HTML5 on mobile apps. In this advent of this industrial shift towards mobile technology, Which demanded a more efficient data loading approach. Facebook decided to rebuild it’s Facebook iOS App from scratch.

| The problem that led to GraphQL

As the development of Facebook app progressed with its initial stage implementation of Newsfeed(which is the first thing that you see when you open a Facebook app), which was backed by the Restful APIs. A lot of issues were encountered.

Slow on Network: Each network request needed to coordinate with multiple linked data models which led to multiple roundtrip requests. There was no hierarchical model for this. It was rather interconnected, nested and recursive. The network requests took a lot of time to resolve which led to poor user experience.

Fragile client/server relationship: Any change to the API needed to be carefully carried over to client code. Which often blocked the client work. This would also cause the App to crash if the changes weren’t carried out properly.

To tackle all these and multiple other issues Facebook decided to develop GraphQL.

| So what is GraphQL?

GraphQL is a query language that describes how to fetch data from one or more data sources. It is a strongly typed language. As the official website for GraphQL puts it,

“Describe your data, ask for what you want, get predictable results.”

One way to understand GraphQL would be to distinguish it from REST. Which is of course why it was invented in the first place. But that is a topic for another day.

For now let’s try to understand some core concepts/keywords in GraphQL:-

1. Schema:

We can define Schema as a contract between frontend and backend which is to say contract for client-server communication. As mentioned above GraphQL is a strongly typed language. It has it’s own type system that is used to define the schema of an API. The syntax for writing schema is called SDL(Schema Definition Language). To understand this let’s define two simple types:-

type Person{    
             
name: String!

age: Int!

}
type Book {

 title: String!
}

We just defined two types Person with 2 fields and Book with a single field. The exclamation mark at the end specifies that the field is required.we can also define a relationship between these types.

  • Relation

To define a relation between the 2 types we just defined above let’s consider this use case. Say a person can be an author to multiple books. We can establish this relationship with the below implementation

type Person{                 

name: String!

age: Int!

books: [Book!]!

}

type Book {

 title: String!

 author: Person!

}

The Square Bracket [] syntax around the book in the Person type is how we specify a list.

2. Queries:

At it’s simplest Queries are how we get/fetch data in GraphQL. To illustrate this let’s write some queries to access the data defined as per the above schema.

{

 person(name: mac) {

  age

 }

If we have a person named “mac” with an age “20” in our data source. This will return a simple JSON response as:

{

 "person": {

   "age": 20

 }

}

Notice the `person(name: mac)` above this is how we pass arguments to in a query.

To expand a bit on this say with age we also need all the books written by the person. Cool! We can do this by a simple query as :

{

 person(name: mac) {

  books

 }

}

That is the simplicity and power behind this language. We get what we need. No more multiple roundtrips and requests. No more unwanted data.

3. Mutations:

Other than requesting data from the backend you might also want to manipulate the data stored on the backend. No problem.

GraphQL provides you with 3 kinds of mutations:

  1. Creating new data.
  2. Updating existing data.
  3. Deleting data.

Mutations follow the same syntactical structure as queries except they always need to start with a mutation keyword.

mutation{

 createPerson(name: "graphql" age: "22"){

   name

   age

}

}

Similar to the query that we wrote above this mutation also has a root type called createPerson with name and age field. In this case, the createPerson takes two arguments that specify the new person’s name and age.

While writing a mutation we can also access the different properties of the new person object. Notice how we are asking for name and age above. This is a cool feature where rather than making multiple queries for the same you can achieve this in a single roundtrip.

The output of the above mutation will look as follows:

{

 "createPerson":{

   "name": "graphql",

   "age" : 22

 }

}

4. Subscriptions:

The most important requirement for many applications today is to have a real-time connection to the server to get immediate updates. For this requirement, GraphQL introduces us to the concept of Subscriptions. Whenever you subscribe to an event it will initiate and hold that connection as long as the subscription is active. Consider the below snippet:-

subscription{

newBook{

  name

}

}

Note: Similar to the query that we wrote above this subscription also has a root type defined.

In the above example, we are subscribing to an event to get informed whenever a newBook is being created. Unlike Queries and Mutations that follow a typical request and response cycle. The subscriptions follow a continuous stream of data i.e, whenever any changes are made on the server-side which is to say in our case that whenever a new book is created we will get updated about the same as long as our subscription is active.

Conclusion:

  1. Define a schema- A schema is a collection of Root types that act as an entry point for the API.
  2. Define Root types. We have multiple root types i.e: Query, Mutation, Subscription.
  3. Root types have different fields on them. Define all the fields.

P.S - That is all for the basics. Hope you understood the basic concepts. Will follow this up with the full-stack implementation of GraphQL.

Start your Digital

Transformation journey

Consultancy | Design | Drupal