What the hell is GraphQL?
With the growing popularity of GraphQL, the obligatory host of more or less founded opinions - trying to tell you that it's all just a hype - is also on the rise throughout the internet.
Some of them have a point, some don’t, and you bet we have an opinion too.
The end of the year is now way past us and I crunched some numbers. The most frequent question I’ve been asked was: «Philipp, could you mute yourself? Your keyboard is very loud.» But that one wouldn't promise a good blog post. So, instead, I will write about the second most frequently asked question: «Why would you use GraphQL instead of REST?»
Honestly, because I wanted to avoid a discussion, which I knew would take too long, I often gave one of the following diplomatic answers: «They serve different use cases.», «It’s a matter of taste.», «GraphQL can’t do everything …»
So here’s my new years' confession: I lied
Common perception of GraphQL
When reading opinions about GraphQL distinct patterns keep popping up. Let's have a look at them.
GraphQL is there to reduce HTTP requests
When fetching complex related data sets with REST, you need to issue multiple requests. GraphQL avoids that by specifying all information requirements upfront. This is true, but just a small part of the picture. HTTP2 would be a better option to just reduce the overhead of multiple requests, without turning everything else upside down.
GraphQL is a supplement to React
GraphQL is not cacheable
A GraphQL query may contain information from different entities, varying fields with arbitrary naming and therefore responses can’t be cached. Responses can be cached, but it’s harder. Besides, it is part of the client’s responsibility to construct queries intelligently, so they can be cached instead of blindly cramming everything into one request.
GraphQL is insecure
Or a less drastic wording: GraphQL has a larger attack surface. Depending on your application, that’s true. Since one query can request a cascading amount of related entities, there’s a lot more potential for something going south. This can be mitigated by designing the schema in a way that doesn’t allow funky constructs or using static query complexity analysis to reject queries that could get out of hand. But both approaches require experience and engineering. It’s definitely easier to safeguard a REST API.
GraphQL is a replacement for REST
That's the big misunderstanding. In my opinion, GraphQL shouldn’t be perceived as an alternative to REST, but as the layer underneath. Conceptually, a REST endpoint is nothing but a persisted GraphQL query.
From a consumers perspective, GraphQL can do anything REST can. Period. There is no valid reason to choose REST over GraphQL.
From a providers perspective, the reduced subset of actions and predictable responses of a REST API are a lot easier to manage.
GraphQL’s elevator pitch
This brings me to the 3rd most asked question of 2017: What’s GraphQL’s elevator pitch?
GraphQL shifts control from data storage and structures to client and product development.
This also answers the question of “when” to use GraphQL: Whenever you want your client to be more powerful. This might not be the case for a public HTTP API. But whenever you control the client, GraphQL is the better choice. And keep in mind that “client” doesn’t necessarily mean web browser, React frontend or smartphone application. GraphQL provides a structured way to describe information requirements that are not limited to HTTP.
It is for example possible to use GraphQL in combination with Twig to turn Drupal’s push-based rendering model upside down and give theme developers all the power they longed for. But this story has already been told.