3 Simple Steps

Install

Totally plug-in-play

# Add the gem to your Gemfile
$ bundle add rails-graphql
# Then run the Rails generator
$ rails g graphql:install

Define

Designed for simple and complex Schemas

# app/graphql/app_schema.rb
class GraphQL::AppSchema < GraphQL::Schema
  field(:welcome).resolve { 'Hello World!' }
end

Run

Follows Rails core principles

$ curl -d '{"query":"{ welcome }"}' \
       -H "Content-Type: application/json" \
       -X POST http://localhost:3000/graphql
# {"data":{"welcome":"Hello World!"}}

Installation

To install rails-graphql you need to add the following to your Gemfile:

gem 'rails-graphql', '~> 1.0'

Also, run:

$ bundle

Or, for non-Gemfile related usage, simply:

gem install rails-graphql

Using Generators

The easiest way to start is by using the generators provided.

# This will create a schema where your objects will be added
$ rails g graphql:schema
# This will create a controller to receive and process the requests
$ rails g graphql:controller

Directory Structure

All your application’s GraphQL schema files should live inside app/graphql. However, Rails::GraphQL will coordinate with Rails the expected classes and modules inside of it, which differs slightly from regular Rails app folders. Think of it as GraphQL’s own app folder.

/ app
  / controllers
    - graphql_controller.rb
  / graphql # Consider it the root of your GraphQL app
    / directives
    / enums
    / fields
    / inputs
    / interfaces
    / mutations
    / object
    / queries
    / scalars
    / sources
    / subscriptions
    / unions
    - app_schema.rb
  / models

This is fully compatible with Zeitwerk.

Those directories won’t be created automatically. Use this as a reference. The ones listed here have special meanings.

Read more about the directory structure.

Setup your Schema

Once you generate a schema, you can add fields and many other things. Let’s set up a very simple field that will return this unique output.

# app/graphql/app_schema.rb
module GraphQL
  class AppSchema < GraphQL::Schema
    query_fields do
      field(:welcome, :string, null: false)
    end

    def welcome
      'Hello World!'
    end
  end
end

Now you can try it out on your Rails console.

:001 > GraphQL::AppSchema.execute('{ welcome }')
    => {"data"=>{"welcome"=>"Hello World!"}}

This is the minimum required to have a very basic setup.

Using a Controller

If you have generated a controller, you may notice that it only has a module added to it. All the necessary functionality is already provided by default. The only thing added for this example is the skip of the authenticity token since we will be using a POST method.

# app/controllers/graphql_controller.rb
class GraphQLController < ApplicationController
  include GraphQL::Controller

  # Added manually
  skip_before_action :verify_authenticity_token
end

Let’s set it up properly by adding a route and running a test.

# config/routes.rb
Rails.application.routes.draw do
  post '/graphql', to: 'graphql#execute'
end

Now, once you have your server running, you can try requesting the result from your application. For the sake of demonstration only, here is a CURL example.

$ curl -d '{"query":"{ welcome }"}' \
       -H "Content-Type: application/json" \
       -X POST http://localhost:3000/graphql
# {"data":{"welcome":"Hello World!"}}

Read more about customizing the Controller.