When and why to use GraphQL.
Design Patterns. Not another ‘How to’ guide.
Many posts about GraphQL focus on how to use it. How to use GraphQL is pretty straight-forward. My hope is that after reading this post, you’ll have an idea of when and why you would want to use it.
What is GraphQL?
If you already know what GraphQL is, you can skip this section.
Simply put, GraphQL is a query language that lets you write queries using an object structure rather than a text string.
So rather than use an SQL query like:
SELECT name, id, description FROM projects
You would simply describe the object and the fields you’d like from that object you like so:
This is great. Graph QL gives you a simple declarative way to retrieve data.
At first glance, I thought to myself:
“Well GraphQL is cool, but hardly worth the effort to do all of that setup for a marginal productivity improvement.”
I thought that the main benefit to using GraphQL was changing the way you send and retrieve data. Quite frankly, my thinking was “in the weeds” so to speak. I missed the big picture.
Why use GraphQL?
Abstraction reduces complexity.
A good number of posts that explain “How to GraphQL” focus on the easy query structure. The thing that made it all “click” for me was when I realized that all off of the requests are sent to a single
Why does this matter? The actual transmission of requests and data is abstracted away. We no longer have to worry about things like response codes and planning out our urls like
We don’t have to worry about the endpoints. This follows a fundamental programming principle of reducing complexity through abstraction. In addition, we also don’t have to worry about all of the
200 OK server response codes, and even some caching on certain clients.
Here are some popular GraphQL clients:
When to Use GraphQL — Web Architecture Patterns
Alright, so why use GraphQL? It’s easier. It’s an abstraction. The next natural question is when does it make sense to use GraphQL?
Chances are, if you have a stable
RESTful service, there’s probably not a strong case to chuck all of that work out. It’s stable and tested, why introduce change and risk?
To me, the real power of
GraphQL is being able to implement certain design patterns on new or existing web services.
It is technically true that any of these patterns could be implemented with a different tool. I’d argue using GraphQL would make most sense in implementing these patterns because the request/manipulation of data (query) is completely decoupled from the execution of those actions (resolvers).
Let’s take a look at some useful patterns adapted for web services taken from object-oriented programming.
The Composite Pattern
Use when you want to aggregate data from multiple places into one convenient api.
Composite pattern - Wikipedia
In software engineering, the composite pattern is a partitioning design pattern. The composite pattern describes a…
Example Use Case: I’m redoing my personal site — jefflombard.com with an Express/GraphQL backend. I can easily aggregate data from my GoodReads profile, my Medium RSS feed, and a MongoDB containing my projects; exposing one simple api to interact with on the front end.
Use when you want to add functionality to an old api.
Proxy pattern - Wikipedia
A proxy, in its most general form, is a class functioning as an interface to something else. The proxy could interface…
Example Use Case: Say you have an old public API, you want to add authentication to it. Firewall off the old one, whitelist your GraphQL server, add authentication to the GraphQL server.
Use when you want to simplify a complex api.
The difference between a proxy and a facade is simple. Proxies — represents the original, perhaps add some functionality like authentication. Facade — simplifies the original.
Facade pattern — Wikipedia
Developers often use the facade design pattern when a system is very complex or difficult to understand because the…
Example Use Case: When you create a new widget on your website, with your old API you have to make three separate calls to do this. Instead you can expose a widget object with GraphQL. When a single call is made to your GraphQL server it will automatically trigger those three supporting calls.
It is completely possible to mix and mash these patterns. For example in a composite pattern you might also need to add a facade to an older api.
Anti-Pattern: Do Nothing Proxy
You should not just add GraphQL as a wrapper to your existing API for the sake of doing so. Most of these patterns that are server to server have performance considerations. Instead if you want to provide the exact same access with a different interface, consider developing a web sdk for your clients.