Advent 2021: GraphQL

Yesterday I wrote about gRPC, which is a high-performance remote procedure call library. This is super useful for services, but if you have a website and you want to provide a “classic”, JSON based API, gRPC is not for you. Instead, you can (realistically speaking) choose these days between two options: A REST API or GraphQL. In the last couple of years, I’ve been increasingly gravitating towards GraphQL, to the point that if I’m setting up a new web API these days I use GraphQL by default.

Why? There are two reasons. The first one is efficiency. With “classic” REST APIs (including OpenAPI) you define the shape of each request and fix it. If you ask for a thing, you get a pre-defined chunk of JSON back, no matter what yo needed from it or not. A good example is if you want to enumerate a list of things and you just need the name/title of each item. There’s really no way in a REST API to describe what you’re asking for, so you end up getting a lot of data that you throw away. On the other hand, GraphQL requires you to pass in the shape of the data you’re expecting to the request. That gets boring real quick for reasonably complex applications. I blogged about this previously in case you’re curious how it looks in practice.

The second reason why I prefer GraphQL is because it’s less work overall. This starts with rather mundane tasks like coming up with an URL structure. GraphQL does away with this, as the structure of the data is the only thing that matters. Next, queries are less complex because there are only two types of queries – mutations and read-only queries. No more question if this is a PUT, POST, or other verb. A GraphQL can be fully explored and queried using the same endpoint, making it easy to discover everything. That’s used to great effect by GraphiQL – you can try that out on GitHub’s API. Finally, GraphQL has excellent tooling these days which makes it really simple to create a GraphQL API. For Django I use graphene-django and effectively my whole API ends up in a single schema file. On the client end, there’s Angular Apollo (which is what I as an Angular user use), which makes it very simple to consume a GraphQL endpoint.

In a world of increasingly complex web APIs, I think GraphQL is a solid step forward. If you’re starting from scratch, and especially if you expose a lot of data, do yourself a favor and take a look at GraphQL!