The GraphQL Endpoint to Understand GraphQL

Over our holiday break at bootcamp, we had the opportunity to learn a new technology not covered in our curriculum. After browsing the list of new technologies to get us started in our research, GraphQL intrigued me most. It seemed like an easier and more organized way of requesting information from an API. It was also intuitive and fun exploring GraphQL APIs, because its schema structure is self-documenting.

When learning something new, I not only like to learn how to use the new technology, but also like to understand why it exists and what it is in nontechnical terms. While I found great documentation on how to use GraphQL, I had to piece that with other resources to understand what it really means in my own words. So, I hope to connect all the information together in this article and create a big picture idea (sort of like a GraphQL endpoint, get it? Not yet? No worries, hopefully by the end this makes sense).

This article will cover:

  • Why GraphQL was created
  • What GraphQL is
  • Differences between GraphQL and REST API
  • Key components of GraphQL

Let’s get started!

GraphQL Origin Story: Shift to Mobile

While they explored traditional solutions such as REST, that didn’t return data in the shape they wanted. They envisioned the news feed data as flexible objects nested in a hierarchical structure, not as information pieced together from cherry-picked URIs.

A post should have an author, number of likes, and a list of comments. Nested inside the number of likes and list of comments, there should be people who have given the likes and authors of the comments. And so spawned the creation of GraphQL, a new approach to interacting with the backend.

While the creation of GraphQL reflects the shift to optimizing for mobile app development, it also represents the shift of development to the hands of client-side developers. With GraphQL, developers can fetch the exact data they need for their app. They are no longer at the whim of whatever information REST API endpoints are programmed to give.

So What is GraphQL?

One thing that really confused me when trying to understand GraphQL was how it differs from something like SQL. To me, it seemed like both were performing the same task, querying and returning data. But it’s important to recognize, GraphQL is an API querying language, while SQL is a database querying language; they both query but perform on different things.

Because GraphQL is thin architectural layer between the client and the backend data (it doesn’t handle the business logic; that’s the job of SQL), you do not have to sacrifice existing backend architecture to use it. If you have REST API endpoints, you can bundle those into one GraphQL endpoint. You can also apply a GraphQL layer on top of a database. It’s versatile and easy to get started!

GraphQL vs REST API

GraphQL, on the other hand, is unopinionated. It does not have URIs hardcoded to deliver specific resources. It exposes one endpoint that accepts a flexible query and returns the exact information the client asks for, nothing more and nothing less.

Here is a fun analogy to visualize the data overfetching/underfetching and multiple endpoints of REST API vs exact data fetching and single endpoint of GraphQL. Imagine you and your vegan friend decide to grab lunch at McDonald’s. You’re starving, so you crave the Land, Sea, and Air Burger from the secret menu and your friend wants the Premium Bacon Ranch Salad, but without the bacon, cheese, and ranch.

If you order from REST McDonald’s, you will need to order three times: once at the counter serving up Big Macs, once at the counter serving up McChickens, and once at the counter serving up Filet-o-Fishes (each counter represents a different REST URI returning a specific resource). Then, after getting your three burgers, you can assemble them into a Land, Sea, and Air Burger. Your friend could order their Premium Bacon Ranch Salad at the Premium Bacon Ranch Salad counter and get their food all at once, but they would get the default salad with bacon, cheese, and ranch. To get the vegan version of that salad, they would need to manually pick out the bacon, cheese, and ranch — how inefficient.

Now, instead, if you and your friend visit GraphQL McDonald’s, you could specify the ingredients of the Land, Sea, and Air Burger at the main counter and you would be able to get the exact burger you want, all at once. Your friend would be able to ask for a salad with only vegan ingredients. GraphQL’s dynamic querying allows you to customize your order, without leaving you in need of a second trip or giving you anything you don’t want.

Key Components

GraphQL has 4 main components:

  • Queries: A Query type is the main entry point for clients to read data; it is the equivalent of /GET requests. A GraphQL API will always have a Query type.
  • Mutations: A Mutation type is the entry point for clients to write data and it defines how data can be modified. It is the equivalent of /PUT, /POST, /DELETE requests. (Although both Queries and Mutations are labeled as “entry points”, they are both nested inside the single API endpoint.)
  • Schema: A schema is the shape of the potential data returned and it is made up of different type definitions.
  • A type is used to describe an object and it includes a field and a type (yes, this can be a recursively nested object!)
  • This is hard to explain over words, so here’s an example code snippet of what a schema and its object types may look like. For context, this is an API for a restaurant to keep track of orders placed by its customers. If you take a look at the Customer type, its fields include a unique ID, firstName, lastName, and Orders. Orders is another object type, so it can resolve into an array of orders with the fields: ID; Food, Customer, and Status. Again, Food is an object type, so it can resolve into the fields: ID; Name; and Price. Because of this recursive nature, a query for a customer can include data on their orders and the food associated with each order.
type Query {
customer(id: ID!): Customer
customers: [Customer]
order (id: ID!): Order
orders: [Order]
}
type Customer {
id: ID!
firstName: String
lastName: String
orders: [Order]
}
type Order {
id: ID!
food: Food
customer: Customer
status: String
}
type Food {
id: ID!
name: String
price: Float
}
  • Resolver: Resolver is any code or logic that evaluates and answers the query. They make the magic happen!

Now, shifting away from technical code, let me try to explain these how main components work with our McDonalds analogy. As a client, the first thing you do is explore the menu (GraphQL schema). The schema is like a menu of offerings listed as ingredients (types and fields) for you to check off. After looking through the menu, you put in your order (sending a query). Then, with the help of employees in the back assembling the burger (the resolver evaluating the query), you are given the exact burger (data) you’ve requested. Tada!

Conclusion

Software Engineer. Love hojicha and a good story!

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