GraphQL for Kids : How a Waiter Delivers Exactly What You Need!

Assume you have gone to a restaurant, and in the restaurant, you want to have fries and a burger, that's it. So what happens here is, let’s say there are three counters you have to go to.

You go to the first counter. The first counter gives you fries and coke, and you’re like, "I don’t want fries and coke. I only want fries." But they will still give you fries and coke, so you bring that. Then, you also want a burger. So, you go to another counter and say, "Hey, I want a burger." Well, they only give you a patty, and now you have to go to yet another counter to get the buns.

That’s annoying, right? What happened to you here is:
You went to the first counter and got more than what you asked for. That’s overfetching. Then, you went to another counter and got less than what you asked for. That’s underfetching.

It’s very annoying, right? You have to go to all those counters and still not get what you really wanted. You have to go to multiple counters to get everything.

Now, let’s say you have a waiter. With the waiter, you just sit down and tell them what you want. So now you say, "I want a burger and fries." The waiter goes to the counters, gets the burger, and gets the fries for you. You don’t have to do anything! This is great—you don’t have to deal with all the stress. You can just ask for what you want, and you get exactly what you needed. No overfetching, no underfetching.

This is called GraphQL. GraphQL acts like a middleman for you, fetching exactly the data you need. It doesn’t overfetch anything. It doesn’t give you less, nor does it give you more.

On the other hand, the analogy of going to counters where you get a little more than what you wanted or a little less than what you wanted is called RESTful APIs, the normal APIs that we use every day.

Now, as we have seen, the waiter does all the job. However, GraphQL is not necessarily the waiter. GraphQL defines what a waiter should be and how they should react. The actual job of being a waiter is done by other libraries. These libraries follow the rules defined by GraphQL to act as the waiter.

So, what does being the waiter really mean?

Yeah, being the waiter has three specific things:

1. The waiter should know what to bring.
   Like in the example, the waiter should bring the burger and the fries, while the burger consists of the patty and the buns. So, the waiter should know what all things he should bring to the user. These are called types.

   Here, the burger is a type. A type is defined as an entity where the burger is an entity, and it contains the patty and buns in it.

2. The waiter should know when he should bring these things.
   Here, we define when the waiter should, let’s say, bring a burger. This can be predefined.
   For example, we can say that whenever you just say "burger," the waiter should bring the burger.

3. The waiter should know when to edit things.
   This means adding sauce to the patty or adding some extra spices to the fries. These are called modifications in GraphQL. Here, you define when the waiter should modify things.

These three things—what a waiter should bring, when he should bring it, and when he should modify it—are combined into something called a schema.

Schema is what being a waiter really means. You have to define what being a waiter is in a given library. Then, the end user (the customer) can call and use your waiter to get exactly the data that they really need.

What Is a Waiter in GraphQL?

As discussed above, we have an understanding of what a waiter is. Now, let’s focus on how to create a waiter.

Remember, in GraphQL, we define what a waiter should do—not how to create one. The process of creating a waiter is handled by libraries. For this example, we will use Strawberry, a popular Python library for GraphQL, specifically created for FastAPI. FastAPI is a simple yet powerful server framework in Python.

Using Strawberry and FastAPI, we will create a waiter to improve customer interactions. Shall we?

The Three Functions of a Waiter

A waiter does three things:

1. Defines what to bring.

2. Decides when to bring it.

3. Determines how or when to modify it.

All of these together are called a schema in GraphQL, while each individual definition is called a type.

---

Step 1: Defining What a Waiter Should Bring

First, we need to define what the waiter should bring. For example, a waiter brings two things:

1. Fries

2. Burger

In this context, the waiter returns a burger, which is a type. Defining a type in Strawberry is simple. Here's the code:

import strawberry

@strawberry.type
class Burger:
    patty: str
    buns: int

Explanation:

• We use @strawberry.type to define a type.

• Here, we defined a burger type with two attributes: patty (of type str) and buns (of type int).

This completes the first step: defining what the waiter should bring—a burger.

---

Step 2: Defining When a Waiter Should Bring It

Now, we define when the waiter should bring the burger. This is called a query in GraphQL.

To create a query, we must define a query type, as everything in GraphQL revolves around types. Here's how to do it:

@strawberry.type
class Query:
    @strawberry.field
    def get_burger(self) -> Burger:
        return Burger(patty="Beef", buns=2)

Explanation:

• We use @strawberry.type to define the Query type.

• Inside the query, we define a function get_burger using @strawberry.field.

• This function returns a Burger object with predefined attributes: "Beef" for the patty and 2 buns.

Now, whenever a customer (user) queries get_burger, the waiter will bring them a burger.

---

Step 3: Creating the Schema

Next, we encapsulate everything by creating a schema. Schema creation in Strawberry is straightforward:

schema = strawberry.Schema(query=Query)

Explanation:

• The schema is defined using strawberry.Schema, and we pass the Query type to it.

• At this point, we’ve fully defined what the waiter is and when he should bring things.

---

Step 4: Creating the Waiter

Now, we need to create the waiter itself. In this context, the waiter is referred to as a router. Here's the code:

from strawberry.fastapi import GraphQLRouter

graphql_app = GraphQLRouter(schema)

Explanation:

• We use GraphQLRouter from Strawberry's FastAPI integration and pass the schema to it.

• This creates the waiter.

---

Step 5: Naming the Waiter and Including It in the Restaurant

Just like a restaurant waiter has a name (e.g., John), we can define a name for our waiter. Here’s how:

from fastapi import FastAPI

app = FastAPI()
app.include_router(graphql_app, prefix="/john")

Explanation:

• We include the router (waiter) in our FastAPI app using app.include_router.

• The prefix="/john" specifies that whenever a user calls /john, this particular waiter will respond and serve the request.

---

Conclusion

Congratulations! You’ve learned how to use GraphQL with Strawberry and FastAPI.

Now, whenever a customer comes to your restaurant (application), the waiter will:

1. Bring exactly what they need.

2. Never give more or less than what they ask for.

By applying this structure in your applications, you can create a scalable, reliable, and efficient system—or, in our analogy, a restaurant where customers are always satisfied.