GraphQL the Bakery: An ELI5 (Explain like I’m 5) for GraphQL 🍪🍩

Recently, I attended the GraphQL Summit 2018 conference hosted by Apollo. It was an excellent event and a great experience for our team at Novvum who has been working with GraphQL since 2015. Prior to the conference, I knew the GraphQL community had been growing quickly, but it wasn’t until I was there that I realized just how fast. This was evident in the companies who attended:

Airbnb, Nike, Netflix, Audi, BMW, Credit Karma, Priceline, and the list goes on.

I think it is safe to say GraphQL is here to stay! It is now more important than ever for companies and developers to begin learning, evaluating and implementing GraphQL.

With that said, it can be a bit daunting to dive into a new technology. I know how difficult it is to grasp new concepts, language, and conventions when you are used to doing something a certain way.

In order to help others in that situation, I felt compelled to create a light-hearted ‘Explain Like I’m 5', otherwise known as ELI5, filled with amusing analogies to help you jump on board and grasp some of the important concepts and lingo. Let’s give it a shot!

Overview

In order to follow a coherent theme, I will describe everything about GraphQL in the context of a bakery. Be aware that this is an ultra-simplified version of the core concepts and just an introduction to most common terms and conventions.

(Shoutout to Henry from Novvum for the awesome artwork!)

Let’s start with some high-level info!

Data

I don’t want to get too granular but I do feel it is important we establish what represents data in our analogy. A node of data or row in the database (1 User, 1 Product, 1 Post, ect.) is represented by each bag of cookies or box of donuts that a customer walks out of the bakery with, while each of the baked items in those boxes are the attributes of that row in the database(Id, Name, Emails, etc.). An individual cookie, donut or eclair represents the attribute or column and the data it represents. So for simplicity, a chocolate donut could represent the name attribute of a user.

Developers / Data Requesting Clients

Customers in the GraphQL bakery will represent any developers, applications or programs needing to access data to build new products and features. This means native and web apps or third-party services/functions

Declare’s “GraphQL” Bakery

First, we need to overview what GraphQL is, and then how it is different from the REST… After that, we will go over some of the key parts that make GraphQL what it is. GraphQL’s most prominent advantage is its declarative nature, so we will head over to Declare’s Bakery to grab some treats and learn some basics.

GraphQL (The Language)

GraphQL at it’s simplest form is a language. In the same way a patron of the Declare’s Bakery orders by talking to the cashier, an application request data from a backend database. You can think of GraphQL as a language similar to English, just specifically made to communicate between applications and servers.

GraphQL vs Rest (It’s a query competition)

Okay, so you may ask how does GraphQL’s language make it different or better than alternatives? Since the REST protocol is the most common alternative to GraphQL we’ll use it for our comparison.

Imagine a competitive and long-standing bakery in a neighboring town. They handle the ordering and fulfilling of baked goods a little differently than Declare's.

At Declare’s “GraphQL” Bakery, customers are allowed to walk in and choose from a well documented and extensive menu. Customers have the choice of purchasing a multitude of different baked items, such as a donut box, cookie bag or an eclair gift box. Since Declare’s prides themselves on choice, they will fill up any or all of the packages and customize their contents to your liking all in one order!

Imagine we order a donut box (User Information) and an eclair gift box (User’s Posts). Inside the donut box, we choose glazed (User Name), chocolate (User Email) and sprinkles (User ID) but leave out the maple bar(User Phone) because it’s not our favorite. In the eclair box, we just stick with the original (Post Count) because it’s all we need for now. Now in a single trip, we got two different treats and everything we needed! That’s awesome!

At Route’s “REST” Bakery, customers have to follow some more strict and opinionated rules. Yes, Route’s Bakery has the same options as Declares, just with less flexibility. For example, you are only allowed to order one box per visit and every box is prepackaged with a set amount of assorted flavors. Route’s “REST” Bakery makes the ordering decisions for you. Say we wanted to make the same order as we did at Declares. First, we would have to order the donut box and receive a pre-determined assortment of flavors, including that unexciting maple bar. Even worse, once we received our order, we would have to get back inline to now order the eclair gift box. Once again, receiving flavors we didn’t want or need. That seems a bit unnecessarily complex and resource intensive...

Once again, This is a simplification of the differences between the two standards, however, it does provide a clear explanation of the advantages of GraphQL. With GraphQL, developers can declare which data they need from the API while avoiding potentially resource intensive pieces of information. GraphQL also reduces the roundtrips needed to obtain relational pieces of data like users and their posts. Request it once, no need to get back “in-line”, GraphQL provide it all in one swoop.

Other GraphQL ELI5 Terminology

Schema (Schema Definition Language)

Every GraphQL API has a defined schema that describes the pieces of data a developer or application can request or make changes to. The schema describes the types and relationships in your data and is clearly typed using a Schema Definition Language. The Schema Definition Language is a concise syntax to declare a GraphQL’s structure. All requests must be validated against that schema.

ELI5: When a patron arrives to make an order at the bakery, they first must review the menu to determine what can be ordered. The menu acts as the “schema” for the bakery and once ordered the cashier will verify the order is actually available on the menu at the time of the request. The menu is written in a specific format and font (Schema Definition Language) and must always be accurate and up to date!

Type

Types are the building blocks of the GraphQL schema. They are a representation of a piece of data that can be queried from the backend. For example, a User type may be defined by a set of fields like name, email, and id. We can even define relationships! For example, when a User owns a Post we can define the User with other types!

ELI5: At the Declares Bakery, a box of donuts, a bag of cookies or a gift box of eclairs could be considered a type. Each of these types can be ordered separately and include a pre-determined set of available flavors (fields).

As for relationships, the analogy breaks down a little... but you could consider ordering a donut box with a cookie bag inside of it as a relationship. The cookie type is available as a part of the donut type.

Field

As hinted above, fields are single units of data that together define a type. A User type will include multiple fields like id, name, and email. Those fields can be further defined as a scalar type like string, boolean or ints.

ELI5: When ordering a donut box (type) customers will receive a set of donut flavors; glazed, chocolate and maple bars. In our analogy, those flavors can be considered a field.

Query & Query Type

In GraphQL, a query is a way you read information in the database. These queries make it simple to request the data defined by the schema. The important part is that the entry points to the API are also defined as a type in the schema. The query type lists the ways the schema can be accessed by developers or applications.

ELI5: As touched on above, a query at the bakery can be represented by the interaction with the employees when ordering the baked goods. However, you can’t just order by saying anything. The bakery menu describes the exact way to order! This means every customer at Declare’s can quickly request information without confusion. How they customize their order is up to them still, as long as they order from the main menu options!

I would like the Number 1, a “Donut Box”, Number 2, a “Cookie Box”, or a Number 3, the “Eclair Gift Box”.

Mutations & Mutation Type

Mutations handle any writing and modifying of data in the database. These mutations are used to update, create or delete data. In the same way a query has a type in the GraphQL schema, mutations are predefined as well. You may only mutate the data in a way explicitly listed by the schema. An example of some common mutations are createUser, updateUser or deleteUser.

ELI5: Let’s say that Declare’s Bakery decides to let customers request changes to the cookies prior to receiving them! Now the patron is asking to add macadamia nuts and peanut butter cups to those cookies. No problem! Declare’s will make the changes then instantly provide the new box of cookies with the customized cookie flavors. Of course, in a normal database, those changes will change for good until a new mutation is made… welp, sometimes analogies break down a bit...

Remember, just like the mutation type, those changes to the cookies must be defined by the menu, but if they are then it is fair game to make some custom cookies! Once requested the employees will gladly fulfill the request!

Resolvers

They are really where the magic happens with GraphQL. Resolvers are functions that connect fields and types to backend data. Resolvers provide instructions for turning queries and mutations into data. You can think of resolvers as the workers of a bakery!

ELI5: The wonderful bakery employees act as resolvers for every order. Complex or simple, the bakery employees will take your order and gladly serve the baked treats!

Subscription

A Subscription, similar to queries and mutations, is a type defined by the schema that provides access to real-time data! This means clients can observe events and receive updates when data changes.

ELI5: Suppose the bakery starts a mailing service where instead of ordering, a customer may receive boxes of donuts anytime a flavor has been updated or changed.

Tools (Bonus!)

Here are some bonus analogies for some of the popular GraphQL toolings.

Prisma

Prisma maps your defined schema to a database automatically! It simplifies database access and maintenance for GraphQL APIs. It lets you read and write data to your database using your favorite programming language.

ELI5: At Declares, it can be really difficult managing the kitchen (database) where the goodies are created and stored. That’s why the owners implemented an ordering and inventory system that quickly alerts the bakers in the kitchen of new order so they can produce the goods and get them to the customer. Prisma provides a similar toolset for managing the relationship between your server and databases.

Apollo

The Apollo GraphQL Platform adds open source devtools and cloud services to implement development workflows and production capabilities that help you adopt GraphQL the right way, incrementally, on top of your existing codebase and APIs.

ELI5: In order to provide quick service the bakery teams needs to be able to input orders, receive money and provide order numbers to every customer. It’s a busy bakery… The team relies on an easy to use POS that accepts orders and handles the transaction. Not only does the system create the connection between order and delivery, but it also monitors it’s speed and provides insights on performance. Apollo plays a similar role for our infrastructure by supporting and monitoring the transaction of Data between a client and the GraphQL server.

Final Thoughts

At Novvum, we believe GraphQL will change the way technology is built. That is why our team is hard at work striving to grow the community and help companies build their best products with GraphQL.

Check us out here: novvum.io

I also hope providing a high-level view of the important concepts helps you better grasp the potential. I am aware there may be some gaps in the analogies logic so please feel free to reach out and provide feedback! I look forward to extending the list to include other relevant concepts like service-oriented architecture.