Many posts about GraphQL focus on how to use it. That part, with a reading, 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:

{  projects {    id    name    description  }}

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 /graphql endpoint.

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 /project/item/somethingElse/youGetThePoint.

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 POST/GET/UPDATE/DELETEcalls,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.

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.

Proxy Pattern

Use when you want to add functionality to an old api.

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.

Facade Pattern

Use when you want to simplify a complex api.

The difference between a proxy and a facade is simple. Proxies — representsthe original, perhaps add some functionality like authentication. Facade — simplifies the original.

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.

Multi-Pattern: Combination

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.