3 Minute Introduction to GraphQL

The following text originally appeared as a tweet thread (with emojis!) on my Twitter account. You can read it here. The text in this article has been slightly modified.

A few weeks ago, I had only heard of GraphQL. However, recently, I gave an hour long GraphQL talk for the engineering team at my internship workplace.

It’s incredible how much you can learn while preparing to teach others.

GraphQL is fascinating.

Below are my key learnings.

GraphQL is a specification, so it is just a document. It specifies a query language for APIs and server side run time to execute them. You can implement it in any language. The original Facebook implementation is in Node. It is database agnostic and transport layer agnostic.

Facebook created GraphQL for internal use in its native mobile apps in 2012 to handle sloppy networks and low internet speeds.

It publicly spoke about it for the first time in 2015 and soon open-sourced it. It is now maintained by Facebook and a strong world-wide community.

In REST, you have a bunch of dumb endpoints which return predefined static structures of data. However, in GraphQL, you have ONE (!) smart endpoint where you send all your queries and let GraphQL handle the fetching of data to build a highly customized response, just for you.

In short, you do declarative data fetching, which means what you ask is exactly what you get.

Doesn’t GraphQL make you feel special?

REST vs GraphQL: No more under fetching or over fetching of data! We all know the pain of updating the view and then realizing that we need more/less data from the back-end. Off we go tapping the shoulder of a back-end developer to modify an existing API or create a new one.

REST vs GraphQL: In REST, we often end up compromising by using an existing API and only picking out certain fields to use. This doesn’t sound too bad until you calculate the amount of unused data that is sent over the network. This can reduce performance over time, especially in mobile apps.

REST vs GraphQL: GraphQL enables rapid product iterations since front end and back end developers can work independently. Moreover, consider the quality of analytics. With REST, we know which APIs are most used, but we have no idea which fields are. In GraphQL, we have analytics for every field.

Building blocks of GraphQL:

1. Queries

2. Schema

3. Resolvers

Queries: Clients send these to specify the data they need. An umbrella term for query (fetch data), mutation (modify data) and subscription (subscribe to events such as creation of a particular record).

Schema: The contract for client-server communication. Specifies what queries clients are allowed to make, the types of data that can be fetched and relationships between types. Defined using GraphQL’s Schema Definition Language (SDL).

Resolvers: Every field has a resolver function, which specifies how that field is connected to the back end and fetches data for that field from a database(s)/ microservice/ existing API. Don’t they sound like our lovely moms, who always know where to find something?

The schema and resolvers make sure that you are only letting clients query data that YOU are comfortable sharing. Using GraphQL doesn’t mean clients can ask for anything and receive it, which is a common misconception.

If you are still concerned about security, remember this: GraphQL is a lot like life. You have the freedom to ask for anything, but you don’t always get it.

However, you are still giving clients a lot of power, and with great power comes great responsibility. You can protect your server by using techniques such as timeout, specifying a maximum query depth and throttling based on server time and query complexity.

You don’t always need a GraphQL client to make requests to the GraphQL server as you can use the simple fetch API. However, using a client like Apollo Client or Facebook’s Relay will provide advanced features such as caching, pre-fetching and more.

This is just the tip of the iceberg of GraphQL but I hope it piqued your interest enough to experiment with it. Shout out to the excellent Official GraphQL site, How To GraphQL tutorials and the Apollo Blog for the high quality of learning material.

Thank you for reading.

Follow me on Twitter and LinkedIn.