Feb 16 2022|Written by Slimane Akalië|programming

Cover image by Gilberto Olimpio.

If you are part of the software engineering community, there is a high chance that you encountered GraphQL. You might have an idea about it or even build something with it, but the story doesn’t end there.

The most common approach to building a GraphQL server is to use the JavaScript rich ecosystem to minimize development time and enjoy your weekend. And JS is cool until it’s not.

In this article, I will share with you why we decided to migrate our GraphQL server from a cool JavaScript codebase to a resilient Golang codebase and what are the things to watch out for.

“Mankind invented a system to cope with the fact that we are so intrinsically lousy at manipulating numbers. It’s called the graph.” - Charlie Munger

Wait a minute, what is GraphQL?

This question is a philosophical one, it’s like asking what is SQL? is it the language or the runtime?

Put opinions aside, from the official website of GraphQL we see a “simple” definition of what this thing is:

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.

If you don’t understand anything, you’re not alone. Let’s try to keep it simple and stupid: GraphQL is a query language that clients use to request read and write operations from a backend service with a clear description of data and an optimal way to expose it: you ask and get only what you need and nothing more.

All the tools that we use to create a GraphQL server are just middlewares to run an http server that offers an API for clients to manipulate/retrieve the data following the GraphQL language.

If we made the analogy to relational databases, in one hand, we have SQL which is the language that everybody agrees on (the equivalent to GraphQL), and in the other had, we have the RDBMS (relational database management system) which is the tool that offers clients an API to manipulate/retrieve the data from the physical files using SQL (the equivalent to a GraphQL API). The implementation of the runtime can differ from solution to another but the language is standard.

The most popular rival to GraphQL is REST, even though this comparison is not accurate 100% because REST is not really a query language, but there are some similarities between GraphQL APIs and RESTful web APIs.

For more information about the differences between GraphQL and REST, go to the home page of graphql.org and scroll down to understand the selling points of this technology.

In the remainder of this article, I will assume you’re familiar with GraphQL basic concepts.

Why stop using JavaScript to build GraphQL APIs?

The most common way to build a GraphQL API is to use JavaScript. With companies like Apollo GraphQL offering some very good open-source libraries, you can have an up and running GraphQL server in minutes, also the community around GraphQL JavaScript libraries is growing at a fast pace. But when it comes to software development there is no free lunch, it’s all about trade-offs.

“JavaScript is the only language that I'm aware of that people feel they don't need to learn before they start using it.” - Douglas Crockford

As always, we should start with why. Why you should leave all this cool stuff in JavaScript to another ecosystem that is less popular?

Actually, you should not unless you have a strong reason to make the switch. Nobody can deny the advantages of using JavaScript to build a GraphQL server, but all the pain points of JavaScript come with this choice also. If you’re okay with them go for JS, otherwise, you might benefit from using another stack.

Here are the reasons on top of my head that pushed us to stop using JavaScript for our GraphQL API in production:

Type safety

The biggest drawback of using JavaScript is the absence of types, this can be okay when you’re prototyping alone, but it’s a nightmare if you have a large codebase with dozens of contributors. A quick solution to this might be using TypeScript (which I love and use for this website) and most developers agree that using TypeScript client-side is good, but when it comes to the backend, there is some controversy.

Some hardcore backend developers believe that JavaScript was historically designed to work on the browser and any attempt to use it on the server-side is doomed to failure, others believe that if type-safety is not supported natively by the language, then adding types is just a hack that could fail in a rainy day (similar to adding OOP on a purely functional language), and other backend developers have ideological disagreements with Microsoft the company that developed TypeScript and maintains it (ironically those same people are using VS Code and pushing to Github every day). Sometimes also, a company can face a shortage of backend developers who know and master the weirdest parts of JavaScript (which can be intimidating even to Brendan Eich).

Performance

JavaScript is interpreted not compiled, which means that the JS engine (V8 in the case of Node.js) will parse your program one line at a time. Compare this to a compiled language where your source code is “translated” to machine-language instructions (or something closer). Now you can understand why C++ can be 10 times faster than JavaScript. In fact, V8 is written in C++.

Infra cost

If you use JavaScript in production and you notice a performance problem, the first step is to examine your codebase and logs, but even when you follow all the best practices and write clean and optimal code, scaling up your servers (either horizontally or vertically) is the solution most of the time because all of these problems are related to the “non-compiled” element of the JavaScript, and you can’t change nothing about this fact.

Ownership

Another element that pushed us to stop using JavaScript to build our GraphQL APIs is ownership. In most software companies nowadays you find at least two kinds of teams: project-based and specialty-based. This model is inspired mainly by the Spotify model.

For the ownership point, we will focus on specialty-based or interest-based teams (call them chapters, guilds, tribes, or whatever). Following this model, you would have for example backend team, web team, mobile team, QA team, and others.

Now, the obvious answer to who builds and maintains a GraphQL API is the backend team or a backend developer, but if your backend team is trying to build expertise in a set of programming languages (or one programming language), usually the team won’t focus on JavaScript.

This can indirectly push web developers to build and maintain GraphQL APIs (especially for small projects), or in the best cases, it will introduce a practice that some engineering managers hate which is “use whatever programming language in the backend based on the use case you’re facing”.

“Freeing yourself was one thing, claiming ownership of that freed self was another.” - Toni Morrison

Why did we choose Golang?

All of the above arguments that made the case against JavaScript were valid for our company, our GraphQL APIs were written in pure JavaScript, no type-safety, performance problems on peak hours, infra cost and so much more.

But the ownership point was the deal-breaker. Our backend team was trying to build expertise in Golang and Java but we got to a point where our biggest GraphQL API was maintained by the web team.

In the remainder of this series, I will assume you’re familiar with GraphQL basic concepts and Golang basic syntax.

“If Go had come out much earlier, I think it might have blown C++ out of the water.” - Bruce Eckel

Why gqlgen was the most convenient option?

gqlgen is a Go library for building GraphQL servers built by 99designs an Australian company that operates a freelancer platform for connecting graphic designers and clients.

This library was the most convenient option for our company, here is why

Talk is cheap. show me the code.

Now let’s write some code, check part 2 of this series to see how to code a GraphQL API using Golang.

“Talk is cheap. Show me the code.” - Linus Torvalds