Introduction to Graphql

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.

I will take a few attempts defining it in just one sentence. Please note that these definitions are not official, but from my understanding of the technology:

  • GraphQL is a language designed for client applications to fetch the exact data needed from an API.
  • GraphQL allows client applications to describe the type and shape of data required from a backend API.
  • GraphQL enables client applications to call a single endpoint for any type of request.
  • GraphQL is like SQL, but for the front end.

Pardon my simplistic attempts at defining such a sophisticated technology, but each of these definitions captures the purpose of GraphQL in one way or another (I wouldn’t use the last one in an interview though :)). This is a high-level view of how GraphQL operates. By the end of this post, you will know it in more detail and be able to build something with it.

So how did GraphQL come to be? What brought about this paradigm-shifting innovation?

It turns out that GraphQL started at Facebook as a project by engineers Lee Byron, Dan Schafer, and Nick Schrock.

The developers on the mobile application needed to work with a lot of nested and interlinked data. To make the application performant, they needed to query the exact shape of the data they needed — to serve modules like the news feed, messaging, and the Facebook wall with posts, along with their respective comments, and likes, and likes for comments under the posts… do you see the problem?

They eventually solved these issues with the technology we now know as GraphQL. While this is good for Facebook, how does this technology help us? How does it make our lives better?

Why GraphQL

Let’s assume you have a blog API that has users. The user data can have properties like ID, name, email it’s kinda like postman like we create and send requests over there and in graphQl it creates existing queries and matches to your existing data.

Now imagine that you need to build these three frontend components:

  • A Profile component that shows user information
  • A Post component that displays a post, its link, and the author’s name
  • An Author component that shows a user’s details and list of post titles by the user

All these components require different shapes of data. With a traditional REST API, each different shape of data would require its own endpoint or require tacking numerous, ugly query parameters to the endpoint. For example, when the front end would request user data, there would be no way of specifying if you only want the ID and email of the user (no name), or you just want the name of the user. The API returns all of the user data. Good luck if your user data contains more parameters than the example above.

You might ask, is it really that expensive to have all the user data returned? The answer is, as always, it depends.

Imagine that you need to show all of the authors on the blog, but you only need to show the names of the authors. If you have 50 authors to display and your user is viewing the page from a mobile application, it will be quite expensive to download the complete user data for each of the fifty authors into the mobile app just to display their names.

With GraphQL, the client is given control over the shape of data to query. The user can simply say something like this:

Get me the users but I only want their names, thank you.

And the API responds with a collection of user data containing just the names of the authors. And you can do this from just one endpoint. Unlike REST, a GraphQL API exposes a single endpoint. This is the endpoint that serves all requests made by the client.

I am sure our heart is now pumping with excitement and you just want to rewrite all of your APIs in GraphQL. Or as a front-end developer, start putting pressure on your API developers to supply you with GraphQL-only APIs. Relax, we are getting there.

How GraphQL Queries Work

So far we have learned that GraphQl is a language spoken by the client, but in what way does the client speak this language? What is the format for sending a request in GraphQl?

Requests are made using a special format that is used to describe the data the best way to learn this format is to write some GraphQl queries. Let’s pick the three components in the last section and write queries for their respective data requests in GraphQL.

A Profile component that shows user information

This component requires a user’s information. In GraphQL, the request would be:

The request above queries the GraphQL endpoint with the user’s ID and gets back the ID, name, and email of the user.

A Post component that displays a post, its link, and the author’s name

This component requires a specific post and the name of the post’s author:

The query above requests a single post by sending the ID of the post. The post is returned with the title and the link. The author of the post is also returned.

An Author component that shows a user’s details and list of post titles by the user

This component needs to get a user and the post titles authored by that user

The query above requests a user’s data and includes with it all the user’s posts, but only retrieves the titles of the posts. In the array of posts returned, only the title of the posts are contained in each post object.

Let’s test out a query on a GraphQL demo created by one of my favorite authors, Andrew Mead. The demo is also based on an API that exposes users and their posts.

We will query for all the users and the title of their posts. Try to write down the query all on your own before looking at the solution:

Did you get it? The good thing about GraphQL APIs is that they are self-documenting and will flag any incorrect query and return helpful error messages.

Now paste the query in the left window of the GraphQL playground at https://graphql-demo.mead.io/ then hit the play button to run the query. You will get something similar to the screen below:

Awesome!

With this, you have a practical demonstration of how GraphQL works. Feel free to play with some queries on the query window to get a better understanding of how querying data works in GraphQL. Click on the little green tab on the right edge of the screen that reads SCHEMA to inspect the structure of the data the API exposes.

Conclusion

What a journey! We went from little understanding of GraphQL to building a simple GraphQL server. There is definitely a lot more to GraphQL than we have touched on in this post. Things like creating a new user and editing user data, saving new posts and paginating your results. Yeah, GraphQL is that powerful. I have also written posts that add continuous integration pipelines to GraphQL APIs. Check out Automatic testing for GraphQL APIs and Continuous deployment of an Express GraphQL server to Heroku.

For more information about GraphQL, visit the official GraphQL site and also check out the server library for your back-end language of choice.

Happy coding!

Wanna learn more about fullstack web development and wanna enjoy learning with community checkout this amazing course called “Zero To Fullstack Hero” here

Thank You!

Darshan Mandade
(PAPA Team Writer)

Python Fullstack Developer | Blogger | Web Developer | Mentor. Let's Connect on IG: @Darshu.codes