Adding GraphQL to Ruby on Rails

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. – http://graphql.org/

This guide will walk through installing and creating a GraphQL API in a Ruby on Rails application. It is a companion piece to the excellent Getting Started with Rails guide from RailsGuides. There are lots of resources that teach GraphQL-itself better than I can, so this guide just focuses on actually installing and using it in a Rails app.

Initial Schema

Let’s first verify that the schema of your app is what is expected for this guide. We will start off right were the RailsGuides guide leaves off. You should have   articles  and comments  tables with the following schema:

Install GraphQL Gem

The GraphQL gem is located at https://rubygems.org/gems/graphql. Find the latest version of the gem, and add it to your Gemfile:

Then run the graphql install command in your terminal:

This should modify the Gemfile to add a development tool GraphiQL, created necessary files in the application, and add GraphQL routes to the route file.

Let’s do a quick status check to see if everything is working so far. Start the rails server, and visit the GraphiQL route,  localhost:3000/graphiql.

You should see the GraphiQL user interface.

Adding Schema

Since GraphQL uses knowledge of relationships between types, we must first defined the types we will allow to be queries. In this case, Article and Comment. Add the following article and comment type files to  /graphql/types

These files define the schema and the relationship between Articles and Comments in a way that GraphQL can understand.

Adding Queries

Let’s add a article query to the api. Open  /graphql/types/query_type.rb  and add the following query below the  :testField query:

You should now be able to execute a query against GraphQL using the Graphiql tool

Here is the text of the query for your copy+paste convenience:

Adding a query to return all articles is just as simple. Add the following query type:

Using the endpoint

Up to this point we’ve used the GraphiQL tool to build and test our API. Let’s move to the actual graphql endpoint, located at /graphql

To test the endpoint you can use a tool like Postman to make requests to the app.

In postman, Let’s make a request to  localhost:3000/graphql (remember to set the header  Content-Type: application/json).

Set the request body to:

In my case, the response is:

Testing errors

Unless you’ve already configured your application differently, at this point it is likely that you will run into the error

Rails, by default, will protect your application from a particular type security risk called a “cross-site request forgery”

A side-effect of this is that you cannot POST to the graphql endpoint unless we temporarily disable this feature, by modifying your application_controller to read:

Please note that this is an important feature, and should only be disabled during developments, or if you want to create a completely public api endpoint.

Wrapping up & Next Steps

At this point we have installed GraphQL into our Rails app, created schemas for Articles and Comments, and written query types to return that data from our application, as well as testing the real API endpoint using postman.

From here you can take any path to consume the data, such as through a front-end application like a React or Angular application, or exposing the endpoint publicly!

Some next steps may be:

  1. investigate a front-end graphql client, like Apollo
  2. fix inefficient queries with batching
  3. look into implementing security

Author: Michael Jasper

Michael is a Web Developer located in Northern Utah. When not programming, he enjoys spending time with his family, exploring the great-outdoors, and hit-and-miss cooking experiments.