Preface

We often hear the phrase, "explain it to me like I'm 5". Even yesterday, I came across an interesting dev.to post with that headline. For a while now, I've been meaning to write about flipping that phrase to "think about it like you're 5". 5 year olds can be fantastic learners, and can be experts at thinking in simple terms. Their terseness allows them to be extremely efficient and effective at getting exactly what they want.

As we all get older, our language skills improve, and we all concern ourselves with formalities and mannerisms. So, if we see a friend eating a candy bar, and we want it, we ask:

"Hi, how are you doing? That candy bar looks delicious? May I please have a piece?"

The child, on the other hand, just says:

"Candy bar!"

Even if the adult holding the candy bar replies, "What do you say?" the child still says "Candy bar!". The adult replies, "You say please" (and still gives the child the candy bar anyway!) and the child laughs, "No, you say please".

The adult has to be concerned with formalities since it is a way of showing respect to other people. The adult knows that if he doesn't show respect in asking his question, he may end up empty-handed...and possibly receive a reply along the lines of "heck no". The child on the other hand gets a free pass, because he may not know any better at that point in time. Lucky kid!

It seems like this adult-way of thinking sometimes carries over into the way we program, and can make us less efficient, making us way too concerned with the framing of a message when it is only the data we are really concerned about. We may forget that when we talk to a machine, and not a human being, we can worry less about mannerisms, and just tell the machine what we want.

Approaching GraphQL like a 5 year old

When I first glanced at GraphQL, it seemed attractive that, as a developer, I could focus primarily on the data and less on the formalities to get that data (because writing laundry lists of API routes was never the job I signed up for). I was also a bit intimidated because I wasn't entirely sure if I was ready to take on a completely different way of thinking. Luckily, the "completely different way of thinking" actually required me to simplify my mind to that of a 5 year old's.

Let's carry over the "candy bar" example to here to explain how thinking like a child makes life easier.

An adult brain coming from RESTful APIs will probably think in terms like this:

http.get('/?candybar=kitkat&size=kingSize').then(handleResp)

The adult has to concern himself with the protocol "http", the special characters "&", "=" and know how to position those correctly. And must remember the ".then".

An adult from an SQL-mindset will probably structure the query like this:

SELECT * FROM CANDYBARS WHERE CANDYBAR="kitkat" AND SIZE="kingSize"

The adult has to concern herself with table names and column names. The adult has to be aware of the tabular structure of the data. It's a lot of typing to get just one candybar. Oh, and the words "SELECT", "WHERE", "FROM", "AND"...that's all English...so, if English is not the adult's native language, the query just became a little more difficult for her to understand...

A child on the other hand would probably just ask for the candy asap:

candybar = 'kitkat'
size = 'kingSize'

Much simpler, right?? Now, this snippet is not actually GraphQL, but it is pretty close. This is how I started learning. My thought process at the time was, "ok GraphQL, you say you're just about the data, we'll make it just about that." I'll evolve my query just a bit to match what I think a JSON-like query should look like, because I think that's what you'd expect: perhaps some curly braces and a comma

{
  candybar: 'kitkat',
  size: 'kingSize'
}

Er...on second thought...omit the comma because a 5 year old may not always be so concerned about punctuation as much as efficiency.

With a mental paradigm in place, it was time for me to do the other thing a 5 year-old does best: play with it. Fortunately, the online tool Interactive GraphQL "GraphiQL" was extremely invaluable. No setup or authentication required. All I had to do was just browse to it and it was ready for my input.

In that playground, I was able to try the above snippet in the coding pane and realize right away the syntax was off. The "result" pane told me what errors there were, and further poking around to the top right corner revealed what Schemas were available. So, eventually, with just a few modifications (and yes, reading the docs), I learned that the above query would be need to be written like this:

{ // <-- NOTE: the word "query" is optional and can be omitted; GraphQL treats this as a query by default. Pretty cool, right?
  candyBars (candyBar: 'kitkat', size: 'kingSize') { // <-- query params
    candyBar // <-- include in resp back to me
    size // <-- include in resp back to me
  }
}

But, a 5 year old may want even more information, even though the actual parameters would remain unchanged. This was easy to do in GraphQL:

query {
  candyBars (candyBar: 'kitkat', size: 'kingSize') { // <-- query params
    id // <-- Makes life easier. See mutations below.
    candyBar
    size
    /* Extra props here: */
    shape // 'rectangle'
    wrapperColor // 'red'
    wrapperHasCartoon // true
    /* <-- keep typing...GraphiQL has intellisense... --> */
    /* type until you get the prop you want. */
  }
}

This addresses the querying, but what about changing the state of the candy bar? The 5 year old may want to bite off a good chunk. So, my thinking originally was something like:

update (id: 123, pctBitten: "50%") {
  size // respond with new size
}

So, in GraphQL, the word isn't "update" it is "mutation". With a little extra tweaking, the snippet just becomes:

mutation {
  biteCandyBar(id: 123, pct: "50%") { // mutations are labeled
    size // respond with new size
  }
}

Even though the word "mutation" is a bit more typing than "update", and may even be out of the scope of a 5 year old's vocabulary, the block inside the mutation may be closer to a 5 year old's thinking. I.e., the mutation to be performed is "biteCandyBar". This also lets the parameter be simplified from "pctBitten" to "pct". It's inferred that "pct" refers to the "pctBitten" because of the mutation's label.

Conclusion

Ok yes, there is a lot more to GraphQL than what I described. This just scratches the surface and to become an expert with it, the responsible developer will probably read the docs comprehensively. However, to get your feet wet, I implore you to think like you are 5! It may just very well reduce whatever fear you might initially have with approaching this new query language.