REST is a Supermarket and GraphQL is a Hot-dog stand

Background

Got confused by the title? Good! Bear with me, I’ll explain.

Most of my articles come from the same source. Well, two sources, actually – frustration and willingness to understand a deeper meaning.

There was a time when I became obsessed with REST. Primarily out of frustration that I couldn’t understand what “that does not conform to REST principles” meant. Yikes! It’s not even REST standards but REST principles. Like, WTF?

And just about a time when I started becoming the “that’s against the REST principles!” activist, a new kid came into a town – GraphQL. And it claimed to have a completely different paradigm! Jesus, a second coming?

I’ve learned a while ago that the best way to find a deeper understanding of the topic is to actually try and explain it to others. So I took quite some time, thinking how to explain GraphQL vs REST without using the phrases like – REST is HTTP-only and GraphQL is query language … Or whatever the heck most of the generic answers are. I mean, yes, those generic answers ARE right, sure. But they are useful only if you know the essence of the matter.

What inspired me even more is one of the videos I recently watched, where professor used an example of Jugs Problem from Die Hard 3, to introduce the concept of prime numbers, greatest common divisor and Euclidean algorithm (here’s the lecture, btw). For unfamiliar, Jugs problem boils down to – given a 3-liter jug and a 5-liter jug, how do you get 4 liters of water (yeah, it’s the same math as for gallons)? And yes, it’s possible. It involves some spilling back and forth, but it’s doable.

So, how do you explain the difference between GraphQL and REST to your 5 year old kid? Let’s see.

REST vs GraphQL

All REST things aside, you need to think about it as a Supermarket. Yeah.

Usually somebody would tell you that if you want to buy milk, bread and alcohol, you can find them at that and that supermarket. Good enough.

We will assume that supermarket is enormously huge, but has no pointers for where what is, hence you can’t simply deduce how to get to milk. The only way to find it is either to wander around or ask somebody. I’ll assume you ask somebody (usually the API creator):

• Excuse me, do you know where can i find Milk?
• Sure, you go straight, left, straight, right and there’s the aisle with Milk
• And do you know where can I find bread?
• Of course, go straight, left, straight and there it is.

In REST terms, Milk and Bread are Resources. Something that you need to fetch. And in order to get them, you need to know their Location (usually referred to as Unified Resource Location – URL):

GET /straight/left/straight/right/milk

GET /straight/left/straight/bread

You got them in two attempts. So far so good.

Valid question would be – why the heck would anyone build a huge supermarket without putting clear signs on where resource are, right? And truthfully, they would have to be an idiot to do so. And yet, we are still seeing lots and lots of REST APIs without proper documentation on where to find what, so go figure …

Putting those signs, usually hanging from the ceiling, that clearly tell you which aisle has what, would be the equivalent of API Documentation. You see how to get there, and then instead of having to ask all the time or wander around, you simply go there. As simple as that.

You know what else is useful? If the aisle with Milk, had some clear signage like – “oh, want a butter and eggs as well? Go that route“. Like, instead of having to look at the ceiling and search for other resources, you simply read the “hints” telling you where to fetch stuff that is usually bought together. That would be HATEOAS. The absolute winner of the Worst Acronym Ever Invented contest. Hell, I guarantee you that one of the reasons why people hate looking into what HATEOAS is, is due to it’s awful name.

HATEOAS stands for Hypermedia as the Engine of Application State, but don’t even bother trying to understand it. To truly get its meaning, you need to understand that REST stands for REpresentational State Transfer, and given that REST gives you a current state of a Resource, HATEAOS tells you how you can change that state (hence the “Engine” part of it – it “drives” the change) and it uses Hypermedia to do that.

What you need to know is that HATEOAS is equivalent to having sign next to a milk telling you – you can fetch butter there. It helps you see where you can easily go from where you currently are. And it’s really a neat thing and hence the pity that it’s not used very often in REST APIs.

What about GraphQL?

if REST is a Supermarket, GraphQL would be something similar to a hot-dog stand.

Got that image engraved in your mind, good?

Before you start thinking about the relative sizes (looking at you, guys!), no, it’s not about the size. The size doesn’t matter (sill looking at you!).

It’s about the concept. If you wanted to prepare a hot-dog using REST, you’d have to go GET hot-dog, GET mustard, GET ketchup, GET hot-dog-bun, etc.

With GraphQL, you have a hot dog seller whose going to do all that for you. Your main job is to explain WHAT you want (e.g. I want hot dog with hot ketchup, mustard, mayo and one coke with that, please) and then wait for it to get prepared. A single action is required from you – a clear description of WHAT YOU WANT, in a commonly agreed language (e.g. English or Chinese) and unless you requested something impossible (e.g. sprinkle it with a HAMMER please), it will be delivered to you in one go:

{
  hot-dog {
    hot-ketchup
    mustard
    mayo
  }
  coke
}

QL in GraphQL stands for Query Language. It describes a common language between you and the seller (e.g. English) used to make queries (“Can I get ….”).

Now, a careful observer might notice Graph in GraphQL. Good catch! Again, just like with HATEOAS, in order to get a full meaning of it, you need to know a bit of a high-school level math that you probably forgot – the graph theory. Graph theory studies the data being represented as series of objects (vertices) that are connected together (edges) into a structure called Graph. Hence, hot dog, bun, mayo and ketchup would be vertices that are related together, whereas a hammer is hardly related (connected) to that graph, making an above request (sprinkle my hot dog with a hammer) rather stupid.

Question you might be asking now is – if REST uses API Documentation and HATEOAS to advertise where can what be found, how do we do that in GraphQL? Simple – by interrogating the hot dog seller! Seriously!

Except that GraphQL calls this an Introspection, but it boils down to similar thing – you interrogate the hot dog seller on what kinds of buns they have, which additions, etc.

One might argue, and rightfully so, that this Interrogation (urm, Introspection) process would be tiresome to both parties – customer and seller. So so. You have to be objective here – how often do you really go and ask bunch of questions to the seller, right? Most of the time you actually know exactly what you want and what is supported, so you just go, make your request and enjoy your free time while they are preparing it.

On the other hand – seller is usually USED to answering these questions so it’s not really a burden to them either. It’s what they are PAID for, after all – to answer questions and prepare your perfect hot dog.

Which one to choose?

Obviously, the difference is in paradigm.

Whereas REST is all about specifying WHAT resources you need (e.g. milk, eggs, butter) and then fetching them one by one, GraphQL is all about DESCRIBING in a single go what you want, and getting exactly that.

Naturally, the question becomes – which one is better.

The most beloved answers, as usual, is – it depends. But, no, seriously, before you start swearing, let me explain.

The answer depends on how your underlying system looks like. Is your data mostly stored in relational databases or did you make a move towards some Graph DB solution?

Next, how experienced are your engineers? And how enthusiastic are they about learning new stuff? And yeah, before you start saying “well everyone has to learn to stay up to date, yadda yadda yadda”, just stop. No. It’s not true and get over it. Some people are enthusiastic about new stuff whereas others prefer stability.

Both REST and GraphQL have pros and cons, but it eventually boils down to how familiar you are with both and how far (or close) your deadline is.

Hence, if you are starting a greenfield project, have an enthusiastic engineering team and some time to wiggle around – go for GraphQL! Frontend engineers will most likely love you for it!

But if you are dealing with a more mature system built all around relational databases, etc. you should at least think twice. GraphQL gives you a QL – a query language, but you need to provide a Graph to be queried!

Positive thing is that modern ORMs seem to have capability of offloading the work of building a graph for you. And if that’s the case for you – very good! Go for it!

Summary

• REST is all about GETTING resources one by one, assuming that you know their location
• GraphQL is all about DESCRIBING what you want and delegating the job of getting it to someone else
• Deciding which one to use should account for multiple factors – familiarity, seniority, current tech stack and deadlines