How to Think in GraphQL Coming From a REST Mindset

Brandon Kraeling

Transitioning to a new tech stack is never a smooth and painless transition. No matter what your experience entails, there isn’t a tech stack out there that doesn’t have a “gotcha”, or at least a few minor syntax annoyances that you have to look up. At the same time, just about every stack has its similarities to something out there that’s widely used, and when you’re a developer with some experience, it’s usually easy to find a path to familiarity.

What happens when the shift is more abstract than a language, a package, or a framework… but an entirely different paradigm of thinking about how APIs work?

As one of Differential’s newer developers, I’m working on my first GraphQL project, after spending the rest of my career in REST-world (with a brief detour to Meteor’s publication/subscription-land). Here's how to shift your thinking to a GraphQL mindset:

1) Tables, not endpoints

When thinking in REST, it's easy to compartmentalize your API calls. A call to a 'users' endpoint manipulates users, the 'widgets' endpoint does something with widgets, etc.

In GraphQL, there's no need to perform multiple requests to get all of the information you need. You can ask for all of the information you need in one request, without having to depend on the API to have an endpoint specifically tailored to your needs.

2) Don't sift through responses... ask for what you need!

Another big difference with GraphQL is that responses come back leaner, since you’re asking for the data you plan to use. This changes how we look for new data.

If I need another field on an object I’m already retrieving, if this was a REST endpoint I’d (probably) already have the field. I could just inspect the object that I’m already seeing in the response, and be able to reference the field accordingly. Of course, I’d have to perform the REST request in a browser or external tool to get to that point.

With GraphQL, I’d add that field to my query instead, and it would be pulled back like we expect. Instead of having to try to hit the endpoint manually, I could use the built-in GraphiQL to run my queries. No browser refreshes needed!

One advantage this gives us is that since we’re using a schema in GraphQL with explicitly defined types, there’s no need to parse through a long response and double-check the variable types.

3) Write data with mutations

If we’re supposed to be looking at GraphQL like we’re looking at a database as we’re fetching data, shouldn’t that apply to changing data as well? It does!

We can use mutations to run create/update/delete queries on our data, using the same GraphQL endpoint. It saves us from having to run POST or PUT requests, and our data checking is done on the server by only defining the data we need in our mutation. No more sifting through a response on the server-side, either, as we already know the types of information we can expect to get since we’ve already told the endpoint what we want to get back from our mutation.

Keeping these things in mind will get you up to speed on GraphQL, and will have you looking at your data layer in a whole new way!