GraphQL

Last updated Jan 28, 2023 Edit Source

According to the official website

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

GraphQL | A query language for you API (no date) GraphQL. Available at: https://graphql.org/ (Accessed: January 13, 2023).

First thing we notice is that GraphQL is not just a API specifications but a full runtime¹ unlike REST which is just a specification.

For GraphQL, just as for gRPC, we need to write specification of the objects we will transfer beforehand. In the GraphQL word, it’s called type definitions and types contains fields.

Example from the official website

First describe the objects

1 2 3 4 5

type Project { name: String tagline: String contributors: [User] }

Then query whatever you want

1 2 3 4 5

{ project(name: "GraphQL") { tagline } }

The result will be formatted just like the query

1 2 3 4 5

{ "project": { "tagline": "A query language for APIs" } }

Those type definition being in separate files, it’s easy to document the API automatically with tools like GraphiQL.

One of the advantages of this query approach is its precision, allowing us to have all the data we need at once, without the need to fetch multiple times like it’s the case for REST.

Drawbacks

From https://research.aimultiple.com/graphql-vs-rest/

1. GraphQL’s single endpoint (/graphql) can be a bottleneck, especially because REST allows easy caching on routes.
2. Security is not built in the standard, different alternatives exist.
3. “While GraphQL offers a caching mechanism, the cache-implementing process is much more complex and time-consuming than REST implementation.” It’s mostly because REST allows caching by using different URLs.
4. GraphQL costs more because queries can be unpredictably large, and a query’s cost can be hard to estimate.

Just like for REST, we could encode files in base64 to upload them. But that adds overhead for both server and client, increasing the file size by ~33%².

Just like for REST, we could use a multipart request but:

Quote from Jens Neuse²

Unfortunately, there’s no standard to handle Multipart Requests with GraphQL. This means, your solution will not be easily portable across different languages or implementations and your client implementation depends on the exact implementation of the server.

So one of the other approaches is to have another homemade API in REST that takes care of files only, or using AWS S3. The last option is not viable if we want to keep our system independent from the cloud.

The article I relied on is made by Jens Neuse at WunderGraph, described as “The simplicity of RPC with the power of GraphQL” on their website. That could be a solution, but would lock us in a not-so-well-known solution, and we don’t control the prices. If I where to use RPC, I would probably go with gRPC which is free, open source and licensed Apache-2.0.