Adopting GraphQL so you can keep the REST

Heads-up. This is not a GraphQL how-to, but a reassessment of the benefits.

I’ve read this analogy somewhere between GraphQL and REST which really stuck with me and I think puts things in perspective.

Let me paraphrase:

But a bit of history first from Wikipedia…

GraphQL was developed internally by Facebook back in 2012 and publicly released in 2015. In 2018, the entire project was moved to its own entity, the GraphQL Foundation, part of the non-profit Linux Foundation.

Ok…and what’s the big deal, you ask? Why should you start using it?

Well, it’s a rather new approach towards API development with an increasing adoption around companies.

It allows API clients to define the structure of the required data, and that same structure is returned back from the server, no more or less.

Basically, it’s a query language (but more) that goes on top of your API, providing you with a single endpoint to consume the entire API and ask for the needed data in a way that is both intuitive and flexible.

You only get what you’re asking for.

Let’s see how…

For example, we have a simple collection of books, with each book having several fields — id, name, author, publisher, publishedAt

On a REST API, making a request to GET /books will return a JSON response containing all the books with all their fields:

1[
2  {
3    "id": 1,
4    "name": "",
5    "author": "",
6    "publisher": "",
7    "publishedAt": ""
8  },
9  {
10    "id": 2,
11    "name": "",
12    "author": "",
13    "publisher": "",
14    "publishedAt": ""
15  }
16]

But imagine you display this data in a simple list on your UI, where you only care about the book name and its id. You don’t need the name of the author, publisher and whatnot, so in REST each time you call GET /books, you will also have unused data in the responses.

In a GraphQL API, you have one endpoint exposed — by default /graphql— that you consume via POST calls.

So for the above case, where you only need the id and name of a book, you call your GraphQL endpoint like this

1query {
2  books {
3     id,
4     name
5  }
6}

which will return a JSON response like this:

1[
2  {
3    "id": 1,
4    "name": ""
5  },
6  {
7    "id": 2,
8    "name": ""
9  }
10]

1query {
2  books {
3     id,
4     name,
5     author {
6       name,
7       email
8     }
9  }
10}

I know…Easy-peasy.

In contrast with REST, this prevents large amounts of data being returned, when there’s no need.

Of course, this is only a basic example showing how GraphQL data fetching makes client application development a breeze.

When it comes to the entire ecosystem, there’s a fair amount of concepts & components to go through — queries, mutations, fragments, schemas, tooling — with quite the learning curve.

The ecosystem & community continues to grow with tools & implementations like claimed industry-standard Apollo GraphQL Platform, an entire platform offering servers, clients & tooling to build your next API.

But if you’re just starting out with GQL and want to stick to the nuts and bolts of it, HowToGraphQL is a good place to start with practical examples for different programming languages (ruby, python, js or go).

If you’re going with NodeJS, you can check out graphql-yoga, an easy way to start a GraphQL, built by the folks at prisma.io. They say graphql-yoga is like create-react-app for building GraphQL servers.

No matter what you choose, try sticking to the basics at first and build a system that you can fully understand and keep lean for as long as you can.

We’ll cover more practical topics like authentication or caching in a future in-depth GraphQL series, using Apollo & React with one of our projects at Haktos as a case study.

Data-fetching

The most compelling feature of GraphQL is the easy data-fetching, which tremendously enhances the developer experience, making modern UI development a delight. It also improves the way the frontend & mobile teams work together with the backend teams.

Microservice orchestration

It’s perfect for a microservices architecture and with schema stitching and Apollo’s federation feature, you can combine services from multiple teams into a single API Gateway, making it easier to scale.

Caching

This is probably the most notorious trade-off, but it’s not necessarily a GraphQL issue, as it is the actual HTTP verb — POST — used to send GQL queries to /graphql . HTTP POST requests are not cacheable, therefore GraphQL caching at HTTP level is simply not possible.

But it seems there’s misinformation around this, making some of us believe that POST requests are the only way to consume GraphQL. However, GET requests are a valid way to send your queries. One caveat would be the size of the query string, which can exceed the limit of some browsers and CDNs.

In comes Persisted Queries and makes things easier, by creating a hash of your query (shorter version) which will be used as a GET request so it won’t exceed browser and CDN’s string limit.

Wrapping up

Despite many sayings, GraphQL does not replace REST, at least for now.

It is an extremely powerful technology and the benefits are clear for most cases. But it won’t solve all your problems.

I know what you’re thinking. “Then why the hype?”

You shouldn’t use some technology cause it’s trending but rather understand the problem you’re trying to solve and figure out if it fits.

If you’re developing a simple API then most probably, instead of simplifying it, GraphQL would add more complexity on top.

So first, try to really understand what you’re trying to build.