Introduction to GraphQL

Among all those fancy technologies around JavaScript ecosystem that are increasing in popularity, GraphQL is probably the one you heard of the least - and that is about to change right now.

In this article, we will focus on the core ideas behind GraphQL and why you should take it into consideration when building APIs for your next project.

Simply put, the GraphQL is a query language for your API. But, what is wrong with REST APIs that we are already used to writing? Let's imagine a situation where you are given a task to build a blogging site. Simple, right?

You build a REST endpoint that retrieves all blog posts and another one that returns a list of blog posts for a specific user. Everything works flawlessly until the client asks you to add the list of people who liked each post - now your route that retrieves posts for a specific user looks like this:

Perfect. Your web view is now ready for development and it should look something like this:

You satisfied your client requirements. But, now that same client wants a mobile app, too. However, the mobile version of the application doesn't show avatars next to people who liked each post. So what are you going to do now? Are you going to build another endpoint that retrieves the same data without avatars for a mobile or are you going to fetch the data and hide the avatars? Both solutions are far from perfect. By making another endpoint for a mobile, you increase the complexity of the project and by fetching more than you need, you are slowing things down. Now imagine that your project scales and, for some reason, you have to split the data into different sources. You see where this goes?! And, you can probably guess what the solution is!

How about a single endpoint that does it all?

Using GraphQL is like talking to a waiter - you tell the waiter exactly what you want, and he gets you just what you asked for - nothing more, nothing less and all that happens in the single round-trip to the kitchen.

With GraphQL on your server, you usually have a single endpoint that works according to your instructions. If you want to retrieve the data from the server, those instructions are called queries (plain strings that look very similar to the JSON) - they look like this:

The query keyword can be and usually is omitted, but for the purpose of this article, I will keep it there. It declares that we want to retrieve the data from the server (GET request) and everything in between parentheses after query keyword represents the data in the format we need. The response we get by calling this query is the same as the one we got in the introduction of this article. However, if we need one argument less (in this case the mobile application doesn't need avatar), we don't need a whole new endpoint just for that. Isn't that awesome? With GraphQL, we get the flexibility that wasn't present with REST API design.

Now let's say that we want to make a new blog post. In that case, we write mutations. The structure is nearly identical to the query string, and you can find more about it here.

Every time we asked for data and got what we needed. But, there must be some limitations to this. Yes - you are right. GraphQL Schema defines those limitations. A schema is a document that has a list of all queries and mutations which the client can ask the GraphQL for. A schema is practically self-documenting so you will never have to worry about documenting your API again (I am thinking about you - REST). Each field in the schema has its type (schemas are strongly typed), and if necessary it can contain short description next to it.

So far, we have gained a solid understanding of how GraphQL works from the frontend side. But, what about the backend? How does GraphQL know where to look for the data that is defined in the schema? Well, computers aren't that smart unless we give them instructions.

Remember our dummy example where GraphQL was a waiter that brings you whatever you want? Food recipes that are prepared in the kitchen are resolvers in that case. Instructions on how to find specific fields from the schema are called resolvers. Resolvers tell GraphQL exactly how to get the data we asked for - they aren't anything fancy, just regular functions that call the database or an external API, for example. The Implementation of resolvers depends on what language you are using. On this link, you can find short examples of GraphQL implementation in different programming languages and technologies.

Give REST a rest and GraphQL a test

In this text, I briefly explained how GraphQL does its magic. GraphQL provides us with great flexibility when compared to traditional REST APIs. However, a greater flexibility brings the additional costs as well. So, nothing is perfect. I will talk more about the problems we have to face when working with GraphQL and the solutions to those problems in the next part of this series. Until then, see how it fits on your side project and try to experience the magic of a single round trip to your server to fetch whatever data you need!