GraphQL – That’s not it!
Maybe you’ve heard of this thing, “GraphQL”. Would you have any use right now for “GQL”, a “SQL” for graph databases? No? Well, if you did, you wouldn’t be looking at GraphQL, as it’s not that. The first impressions people form when they see the name “GraphQL” tend to stick and they could not be more wrong. I made the same mistake.
I’ll write a separate post on what it is. Before we get there, it is important to clear our minds of misconceptions, what is not. Believe it or not, even GraphQL practitioners have them and are held back by those. So, if you do “know” what GraphQL really is, I would still very much appreciate you reading this – maybe you’ll discover something or, maybe you can reveal something to me.
Each section deals with a misconception that either I had myself or have frequently observed. Let’s begin.
Graph? What Graph?
Have a look at the specification, say the October 2021 one, the latest at the moment I’m writing this. Try to find the word “graph” in there. Ignoring substrings of 269 appearances of the name “GraphQL”, here’s what I found:
1 appearance in the comment of an example of questionable importance, it may easily be omitted: “user represents one of many users in a graph of data”.
1 appearance in a sentence stating what must not happen: “The graph of fragment spreads must not form any cycles including spreading itself.”
Let’s dig deeper:
There are two appearances of “edge”, one in “edge-cases” and another in “acknowledgement”.
Neither “vertex” nor “vertice(s)” appears anywhere.
No, it has nothing to do with graphs. It can be used with graphs but it isn’t unique in this manner. The spec itself states that GraphQL is “hierarchical” and it mentions trees a few times. That’s the closest you’ll get. But don’t call it TreeQL. That’s its own thing with a website that seems to want to look very much like GraphQL’s.
In this context, the “graph” appears to simply refer to the fact that everything in this world can be thought of as a graph, and, although GraphQL doesn’t directly deal with concepts commonly associated with graphs that some languages do, it can be used efficiently to handle graphs, specifically acyclic.
QL? What QL?
In the same specification, there is no direct explanation what “QL” stands for. There are three occurrences of the words “query language”, always next to “GraphQL”, thus implying that GraphQL is a query language. OK. What does “query language” mean to you? Do you associate that with some way, syntax, to express your search needs? Should it include search criteria or conditions? Well:
The spec includes no occurrences of the word “criteria”
There is one occurrence of the word “expression”, specifically in the following sentence: “… therefore GraphQL lacks the punctuation often used to describe mathematical expressions”.·
There is one mention of the word “operator”, but it isn’t for what you may think it is. There are no data/value manipulation or comparison operators. GraphQL has nothing that would let you say “a = b”, “c < d” or “e + f”.
But guess what – the word “condition” appears 30 times. Better yet, it is related to whether some data should be included or not. But guess what? If you’re thinking of the SQL’s “WHERE” clause, this is not it. This is more akin to which “columns” to include and what would be the projection clause right after “SELECT” in SQL. And, not, this has nothing to do with SQL. You won’t find criteria hidden under any other name in the specification either. It just isn’t there.
Technically, GraphQL is more correctly a “projection” language without “selection” features. The word “query” in GraphQL is overloaded and used in at least four different ways:
“API request”. GraphQL is an “API request language”.
A classification name for read-only operations (that you define, not GraphQL)
A name of the standard output (structure) type, whose content you define, without you it doesn’t exist.
A keyword construct acting as a sort of a named singleton giving client access to whatever you put in (3).
But, I’ll get into details in another post.
Database? What database?
There is a single mention of the word “database”, as a side note on the possibility of reliance of a particular implementation on the database for an asynchronous execution flow. There are no mentions of “repository”. There is a mention of “storage”, quote:
GraphQL does not mandate a particular programming language or storage system for application services that implement it.
The only mentions of the word “column” relate to the text column number together with the line number. The letters “table” appear as ending of “executable”, “printable”, “repeatable”, “representable”, “stable”, “notable” and “predictable” except in a table of Unicode characters. The letters “row” only appear in the word “throw” (an error).
Does that clarify it?
GQL?
Some try to shorten “GraphQL” or think of it as “GQL” and pronounce it “jequel”. Not only that evokes more incorrect associations with SQL but happens to be the name of something completely different: GQL. Yep, that exists. No, it’s not GraphQL. Yes, it is a “graph query language” and, yes, that one is about “SQL for graph databases”. And, yes, it does have the graph-specific concepts and terms that GraphQL does not.
Bulk updates and deletes and other scary stuff
Neither “bulk”, “batch”, “update” nor “delete” letters appear anywhere in the GraphQL specification. There is nothing in there about these. There is a scary word “mutation” but it is much like “query”, little more than a classification of operations that you have to define. It would mean that the operation you made “has side-effects” or “writes” and isn’t just “read-only”. That’s all.
Guess what – GraphQL doesn’t actually specify anything. It comes completely empty. As in “there’s literally nothing there”, “zero”, “zilch”, “nada”. It does not define any out of box operations whatsoever. It doesn’t even come with assumptions of any operational abilities. That sounds completely useless, then, right? Without revealing too much, it helps to think of GraphQL not as a single query language but as two languages. One is a meta-language that one uses to make the other, a domain-specific language. Don’t let that scare you off, it is trivial. The point is that you get to design what it is and what can be done with it. It only provides the standard structure, the scaffolding.
“It’s probably binary or otherwise nasty”
GraphQL responses are JSON to a fault. That’s it. It doesn’t do binary. GraphQL requests are plain text, sometimes within JSON. While GraphQL can be exposed other ways, I know of no implementation other than “over HTTP”. Simple HTTP GETs can execute queries and POSTs can do more. You can curl a GraphQL query from a command line.
Both requests and responses are concise and efficient. If you remembered SOAP and various “thick envelopes” and cumbersome structures, you can safely put that memory back where it came from. GraphQL responses will be smaller and more to the point than, say REST.
“Current clients I have can’t use it”
If a client can use REST APIs, they can use GraphQL. Every single one of them, without exceptions. In fact, some confuse the two and think that GraphQL is just a feature of a REST API. It’s not. Every GraphQL API can be covered by a single Swagger / Open API spec, so if you can access such APIs, you can use GraphQL.
“Must be hard to implement a server”
If you use a framework for both, the mechanics of the implementation is about as hard as implementing a REST API. There are ready frameworks for just about any language you may conjure up. Designing the API, however, is much easier with GraphQL than with REST because the paradigms and constraints are very different and match the real world much better. Not convinced? Try going through the exercises I described in my earlier posts on REST API. Do start from part 1 before seeing part 2 and part 3. Then learn about GraphQL and work them out again. It won’t take long at all.
“It’s a niche thing, nobody is using it”
Check that again. For example, you can have a look at the GraphQL “Landscape”. OK, that one is likely biased. How about Google Trends? Hey, there’s a documentary about it too. Do whatever research you like. The only thing you need to be careful about is that “rest” is not only “REST” but many other things (vacation, break, calm, pause, remainder, etc.) and most people use “REST” without knowing what it is. Pay attention to the related queries in Google Trends. There can be no confusion with GraphQL but for RESTful it is about “rambles” and “asmr” even when restricted to the “Computers & Electronics” category and, when not, includes “music”, “sleep” and “meditation”. If you opt for “REST” instead of “RESTful”, it becomes correlated with Bruno Mars, Maher Zain, Pentatonix, Sefo, Lil Skies, Ludacris, David Guetta and more (at the time I wrote this).
“It’s just a wrapper, will slow things down”
Very often, when someone is transitioning from the approach “A” to approach “B”, that “B” may begin as a complete or partial wrapper of “A”. This is not specific to GraphQL and applies to it too. It does not need to remain that way. GraphQL can be implemented as a wrapper. It doesn’t have to. It can iteratively evolve from being a wrapper to a native implementation and then continue to enable functionality and performance not previously possible. Even if/while in the wrapper stage it can offer performance advantages by acting as a communication latency and size optimizer and help with any micro/macro service refactoring you may be thinking of via functional composition. Acting as a wrapper is, thus, either only transient or beneficial, or both.
“It’s harder to secure”
Statements like this often come from people who are only experienced in securing something else and have not had the opportunity to work with GraphQL yet. They are often scared because they have some of the misconceptions noted earlier. I too had some of these. It turns out that GraphQL matches the real word better than, say REST. That allows more direct mapping of client behaviours to GraphQL requests and response structures and that, in turn, enables better access control and malicious request recognition. I plan a post on this later but, for now, have a look at Paniql, Apollo’s complexity limits, TypeGraphQL Query Complexity, and Stellate’s Complexity-based Rate Limiting.
