How to Configure and Use GraphQL with Rails

GraphQL + Rails

In this article, I’ll briefly describe the basics of configuring GraphQL with Rails and the basics of the GraphQL query language. After this article, you can modify things and easily use them in your apps.

1. What is GraphQL
2. Comparison GraphQL with Rest
3. How to Configure it with Rails
4. Testing Tools
5. What is JSON
6. Queries
7. Mutations
8. Front-end Example

What is GraphQL

Rails is a framework that is written on top of the Ruby language. GraphQL is a query language for your API. It was written by Facebook in 2012 and open-sourced after three years. With GraphQL, you get predictable data, ask just for what you want nothing more than that on your queries, and request multiple objects in the same query. There is also a built-in type system that you can check here.

GraphQL vs. Rest

GraphQL vs. Rest

How to Configure it with Rails

The first thing that you need to do is create an empty Rails API project.

rails new my_api -–api

You can even configure different database management systems, and for more, you can refer to it here. For simplicity, I’m not changing the default SQLite.

And then, you need to put the GraphQL gem into your gem file. You can reach the gem repository from here.

After that, open a terminal in the root folder and run.

bundle install

This will install the necessary folders into your system, and all we need to do is now run the generator that will create a GraphQL folder, and inside, there are some pre-configured arrangements.

rails g graphql:install

Those steps are for configuring the ready-to-go version of GraphQL. And from there, we’ll build our queries and mutations. If you check now, your folder structure, you’ll see a graphql_controller, a GraphQL folder, and a GraphQL route in your app.

Testing Tools

GraphiQL is a GUI for editing and testing GraphQL queries and mutations. You can use some different tools as well. I’m giving a source to test your GraphQL endpoint here.

What is JSON

JSON is a relatively new and open standard for transmitting data objects consisting of attribute-value pairs. Attributes are always strings, and values can be different data types (Strings, numbers, dates, arrays, null…). In GraphQL, JSON is used to communicate and transmit data. If you are curious, you can read this wiki page.

Queries

We now have a GraphQL folder; inside it, there are two folders. We are now concerned with the types folder, and inside there is a file called query_type. When we first look at it, there is a default query that we can investigate and remove

In this default query, if you realize that we have a field called test_field type of String, it can not be nullable. If we want to work with GraphQL, we must define those parts. Name of the field, type of the field, and if it can be null or not. Then there is a resolver method with the same name as the field. When a query comes to our GraphQL endpoint, you can check the route file below, the routing goes to the GraphQL controller, and from there, it comes to this file, and depending on our query field, it looks for the field name and its resolver method. The resolver method returns something that matches the field type, and we can reach the return value in our front end.

Also, if you check our route file, you realize that our default route is now GraphQL, configured via our generator command.

If you would like to give some arguments to your query, you can use the field part as a block and make the necessary arrangements as below.

Above, we give our query an argument and arrange our employer field returns the Employer instance provided with the id. Also, in this gist, we define our own type instead of the default types that GraphQL gives us. Our EmployerType file is below; you can look at it.

If you check this file, you’ll realize there is a full_name method. This method is our custom method which uses two of our fields. You can customize your return fields, as in the example.

I want to mention one last thing about queries. If you would like to have something to share with your fields and your controller, there is a context part in the graphql_controller. For example, there, you can share session-based information between your front-end controller and the GraphQL fields.

The gist above is mainly configured via our generator command. The only thing that I want to mention here is the context part and the session-based information that I can share with my fields. You can take this context in your fields and use it however you want.

Mutations

In GraphQL, data is changed via mutations. It is the same syntax, and you just need to call the GraphQL endpoint with the necessary data, and it’ll make the required changes in the backend. There are two ways of doing this. Whether you can put your mutation inside the mutation_type folder or create a separate file for mutation and use this file, those are doing the same thing but with different architecture.

The example above shows two different versions of mutations. For creating, we are using a separate file and implementing our mutation logic there. For update or deletion, we are using the same mutation_type file. On the front end, again, we need to make a post request to the GraphQL endpoint and ask for the change we want. To create an employer, for example, create_employer.

Front-end Example

I won't dive deep into the front-end part because you can use different tools and make some GraphQL calls. I generally use React on my projects and Apollo GraphQL was nice to use so I’m giving here its docs. Also as a small GraphiQL example of an employer creation for our case;

Thanks for reading!