markdown guide

It's lunchtime at school and they're serving your favorite meal: Meatloaf and mashed potatoes.

You really like the meatloaf and mashed potatoes part the most, but you're a good kid so you know you need to eat your peas and carrots. You are excited about the corn and of course, the gravy.

But you don't want your plate to be covered in veggies, yuck! So you need to be specific about what you ask for. You need two scoops of mashed potatoes, a big slice of meatloaf, half an ear of corn, and about a fistful of peas and carrots. But communicating all this to the cafeteria chef is a mouthful.

That's why you use one of these:

It's a GraphQL tray. It shows the chef exactly the portions you need and all you have to do is hand over the tray. The chef is going to then scoop out the portions from their big Mongo vats of meat, potatoes and the rest. Some chefs use Postgres tubs. Maria and Cassandra brand tubs are also popular in some school districts. But none of that really matters to you. It might matter if you had to give the chef specific instructions, but it's his job to figure out how to scoop out the mashed potatoes and fit the into the shape of your tray.

Some cafeterias don't let you use a tray to get your food, and you have to come back for each thing you want.

For a while the cafeteria workers were RESTing easy with this system which was simpler than other SOAPy systems and is still perfectly useful for a lot of cafeterias. But this district thought that that was getting a bit chaotic and that's why they started letting kids bring trays to get all the food they need without having to make a bunch of trips or have to explain to the chef exactly how much of each they need.

The kids seem to be happy with the new system.


I guess you have to explain a lot to 5 year old kids? :D Great comment though!


Your comment in the other thread got me thinking GraphQL and motivated me to answer this one 😊


Imagine you have a Lego set, let's say a StarWars Tie Bomer Classic and you want to make the wings first, using REST will dump the whole Lego set on your lap whilst using GraphQL you will only get the pieces you need to make the wings.

Make sense?


Maybe I'm stretching the analogy too far here, but the compartiments in your tray can have little labels to indicate what should go where. So if, like me, you prefer carrots over peas, the server can just pick those delicious sweet things out for you, you don't want the peas taking up space in your tray, as that makes it heavier to carry back to your table.


This is an awesome explanation! adding to Pocket


One must have a bunch of kids to come up with such a cool intro to GraphQL! <3


I was very confused about GraphQL before reading this. It all makes sense now. Thanks @ben


Omg, I love this πŸ˜‚ awesome explanation!


Wow, this was a great explanation, thanks man


REST is like normal television, once you are on a channel, you have to watch what's on it at that moment.

GraphQL is like Netflix, you can pick what you want, as long as it's in the catalog.


I'm not sure how to explain something like that to a 5 year old but GraphQL is just a specification to request information. It describes a language you can speak to a GraphQL backend. I'll try that anyway!
The backend (mother/father) reads the query (your phrase) and they gives you what you want, for example they know about a lot of books and their authors, amount of pages, etc. You want to have a list of titles of books written by George von Devto but you don't care about the amount of pages in them. So instead of asking your mom/dad to just give you the books and filter the data by yourself (exclude anything but author:"George von Devto", exclude the pages count from the data), you only ask them for the titles and they do that for you. That's how it works. At least that's how I understand GraphQL.


Oooh, nice!

Anyone know why it has Graph in its name? This whole time I thought it was something to do with data viz!


It has Graph in its name because the data is structured as a Graph Data Structure, as opposed to the Linked List (i use this term very loosely) style REST APIs. The key difference is that having "nodes", as is the case for GraphQL, allows you to coalesce data from multiple "nodes" while with conventional REST API is more linear in its data retrieval.

The cool thing about nodes is that you can reference yourself (i.e the same node); it can be recursive.

Let's say you have a user object, which contains a list of friends, denoted by their UUID. We are particularly interested in the names of your friends, so what we can do is this

  user(uuid: "8f7ab4") {
    friends {

What ends up happening is that in a single request we go from one user (given by a user object), get their friends list, and for each friend (also given by a user object) fetch their UUID and name. This is all made possible by how the data is structured. With a REST API, you'd have to query for each of the users by UUID, perhaps by using user/<friend-id>, returned from a user/8f7ab4/friends API call. Even more important is that the REST API call will return tons of information that you dont really care about, effectively costing you more for bandwidth and also resulting in high latency in completing the actual query you're trying to execute.


I remember someone briefly explaining this in some conference talk, but I can't seem to find it. It has to do with how GraphQL allows you to think about and traverse your data and the relationships between them as if you're traversing nodes and edges in a graph.


I don't know about the Graph part too (and Wikipedia doesn't know about that as well). I think the idea is that your queries kinda visualizes the data you're asking for. I mean it's not that hard to understand what I'm asking for in this query:

query {
  books(author:"George von Devto") {
    comments(rating:">=4") {

I think it's because you can think of each entry as a node, which has edges that connects to other nodes.


So can I see it as an abstraction layer for any (supported) database?


Yes. It's an abstraction level for any data, it doesn't matter if it's a database or something else. As long as your code returns the data someone requested, you're fine. ☺


That's an interesting explanation and I really like the school cafeteria analogy! HOWEVER, I actually think there is a major flaw in it - here's how I would see it:

The GraphQL tray that you mentioned is actually a REST tray as it has a fixed structure! It won't let you (the 5year old student) decide what you actually want but only provides you with the things that have been prepared for you by the cafeteria in predefined portions.

Now is fantasy time! Imagine the next time you're at the cafeteria, you can tell them exactly what you like! GIVE ME THE WHOLE MEATLOAF! I WANT THAT PIECE OF CORN! NOOO PEEEAAAAS!!!!!! That's GraphQL - it gives you all the flexibility you could wish for when asking for stuff (i.e. data) instead of forcing you to ask in terms of fixed and predefined portions (i.e. structures).

Quick plug: If you want to learn more about GraphQL, check out the fullstack How to GraphQL tutorial website :)


It's like you, as a child, between your parents, when they are upset on each other.

Mother says: - tell your father to buy these groceries, gives you the list.
You deliver the list to your father. Your father goes to multiple stores, buy stuff. On the list is also "pay the electric bill", he goes and pays that too.

He returns with the goods. You take the goods and deliver them to your mother.

Mother = the Client
The list = the query
Father = the server
The Stores = the data sources (databases, files). Electric bill - 3rd party service like post on a twitter account.
You = graphQL
The goods and the receipt of the bill = the GraphQL response


Maybe we can use the banana analogy on this?

For example, I want a banana.

Using GraphQL is like asking for a banana and actually getting a banana, instead of asking for a banana then getting the banana but with a gorilla holding it -- along with the whole forest.

With GraphQL, you also don't care where the banana comes from as long as you get it.


Thanks everyone, I didn't even know GraphQL "existed" (even though I suspect the Facebook Graph API is a REST API on top of GraphQL). Now I know what it does and it's clear to me. It seems awesome! :-)


I made a presentation in my company. Maybe this can help you get started



Thanks! I'm pretty familiar with GraphQL. I just wanted to find a great analogy for explaining GraphQL because I'm also going to give a talk. :smile:


Love the explanation! Now I am hungry...


Once I read that : only who has a deep knowledge about something is able to explain it in simple way


That was probably Richard Feynman.