K-Sato

Posted on Dec 25, 2018 • Edited on Mar 3, 2019

GraphQL Ruby(Class-based API)

#graphql #ruby #rails #api

Introduction

I'll walk you through how to use GraphQL in your rails applications using GraphQL Ruby.
We will create a very simple api which users can get, create, update, delete posts.
You can check the source code here.

Basic concepts

Let's cover some of the very fundamental concepts of GraphQL

Schema

The schema defines the server’s API.
It provides the point of contact between the server and the client. You have to create one for queries and another for mutations.

Type

The shape of everything composing the schema.
Each type has a set of fields which defines the data that the type should return.

Resolver

Resolvers are functions that the GraphQL server uses to execute fetching(queries) or mutating(mutations) the data.
Each field of your GraphQL types needs a corresponding resolver function.

For more information about the basic concepts of GraphQL, Check the official guide .

Installation

GraphQL with Ruby on Rails

Simply, add graphql and graphql-rail to your Gemfile.

# Gemfile
gem 'graphql'
gem 'graphiql-rails'

If you want to use graphiql-rails for your api only rails application, add the following line to your config/application.rb.

# config/application.rb
require "sprockets/railtie"

After adding the gems and the line, run the commands below. The second command will create the app/graphql folder.
All the graphql related files will be held under this directory.

$ bundle install
$ rails generate graphql:install

Queries

In GraphQL, Queries are used to fetch data and Mutations are used to create, update and delete data.
In this section, we will focus on the queries.

Create a model post and run rake db:migrate.

$ rails g model Post title:string description:text
$ rake db:migrate

Create some data on rails console.

$ rails c
$ Post.create(title: "What is Ruby?", description:"Ruby is a programming language")
$ Post.create(title: "How to learn Ruby", description:"Read some books brah")

Define the GraphQL Type for Post in app/graphql/types/post_type.rb.
If you run the command below, it will automatically create Post Type for you.

$ rails g graphql:object Post id:ID! title:String! description:String!

The command above will generate this.

# app/graphql/types/post_type.rb
module Types
  class PostType < Types::BaseObject
    field :id, ID, null: false
    field :title, String, null: false
    field :description, String, null: false
  end
end

If you want to know the details about Class-based system, read official graphql-ruby document..

Query Resolver

The type is now defined, but the server still doesn’t know how to handle it. We use resolvers for executing the queries.

All GraphQL queries start from a root type called Query. When you previously ran rails g graphql:install, it created the root query type in app/graphql/types/query_type.rb for you.

With the code below, you can retrieve all posts and each specific post using its unique id.

# app/graphql/types/query_type.rb
module Types
  class QueryType < Types::BaseObject
    field :posts, [Types::PostType], null: false
    def posts
      Post.all
    end

    field :post, Types::PostType, null: false do
      argument :id, Int, required: false
    end
    def post(id:)
      Post.find(id)
    end
  end
end

Testing with GraphiQL

Add the following code to your routes.rb.

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

  if Rails.env.development?
    # add the url of your end-point to graphql_path.
    mount GraphiQL::Rails::Engine, at: "/graphiql", graphql_path: "/graphql" 
  end
end

You can test your progress using http://localhost:3000/graphiql after you start your rails server with rails s.

If you want to get all the posts, send the query below.

# Query for posts
{
 posts {
   id
   title
   description
 }
}

################ Result #####################
{
  "data": {
    "posts": [
      {
        "id": 1,
        "title": "title1",
        "description": "description1"
      },
      {
        "id": 2,
        "title": "title2",
        "description": "description2"
      },
      {
        "id": 3,
        "title": "title3",
        "description": "description3"
      },
     ]
   }
}

If you want to get a specific post, send the query below.

# Query for a post
{
 post(id:1) {
   id
   title
   description
 }
}

################ Result #####################
{
  "data": {
    "post": {
      "id": 1,
      "title": "title1",
      "description": "description1"
    }
  }
}

Mutations

All GraphQL mutations start from a root type called Mutation.
This type is auto generated in app/graphql/types/mutation_type.rb.

module Types
  class MutationType < Types::BaseObject
    # TODO: remove me
    field :test_field, String, null: false,
      description: "An example field added by the generator"
    def test_field
      "Hello World"
    end
  end
end

Mutation Create

Run the command below to generate a mutation for creating a post.

$ rails g graphql:mutation CreatePost

The command above will do the folliwing two things.

(1) Create graphql/mutations/create_post.rb.
(2) Add field :createPost, mutation: Mutations::CreatePost to graphql/types/mutations_type.rb.

# (1) Create graphql/mutations/create_post.rb.
# graphql/mutations/create_post.rb
module Mutations
  class CreatePost < GraphQL::Schema::RelayClassicMutation
    # TODO: define return fields
    # field :post, Types::PostType, null: false

    # TODO: define arguments
    # argument :name, String, required: true

    # TODO: define resolve method
    # def resolve(name:)
    #   { post: ... }
    # end
  end
end

# (2) Add  field :createPost, mutation: Mutations::CreatePost to graphql/types/mutations_type.rb.
# app/graphql/types/mutation_type.rb
module Types
  class MutationType < Types::BaseObject
    field :createPost, mutation: Mutations::CreatePost
  end
end

This part is optional!!!

You can create graphql/mutations/base_mutation.rb and make graphql/mutations/create_post.rb inherit from it.

# graphql/mutations/base_mutation.rb
class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
end

# graphql/mutations/create_post.rb
module Mutations
  class CreatePost < Mutations::BaseMutation
    # TODO: define return fields
    # field :post, Types::PostType, null: false

    # TODO: define arguments
    # argument :name, String, required: true

    # TODO: define resolve method
    # def resolve(name:)
    #   { post: ... }
    # end
  end
end

After making create_post.rb inherit from Mutations::BaseMutation, let's follow the TODOs in create_post.rb and modify the file like the code below.
(If you did not follow the optional part, create_post.rb still inherits from GraphQL::Schema::RelayClassicMutation in your file.)

module Mutations
  class CreatePost < Mutations::BaseMutation
    graphql_name 'CreatePost'

    field :post, Types::PostType, null: true
    field :result, Boolean, null: true

    argument :title, String, required: false
    argument :description, String, required: false

    def resolve(**args)
      post = Post.create(title: args[:title], description: args[:description])
      {
        post: post,
        result: post.errors.blank?
      }
    end
  end
end

That's it! Now you are ready to create a post!.

Testing with GraphiQL

You can test your progress using GraphQL after you start your rails server.
Make a request like the code below and check the result.

mutation {
  createPost(
    input:{
      title: "title1"
      description: "description1"
    }
  ){
    post {
      id
      title 
      description
    }
  }
}

################ Result #####################
{
  "data": {
    "createPost": {
      "post": {
        "id": 15,
        "title": "title1",
        "description": "description1"
      }
    }
  }
}

Mutation Update

Run the code below to generate a mutation for updating a post.

$ rails g graphql:mutation UpdatePost

Modify /graphql/mutations/update_post.rb like the code below. It is very similar to the code in /graphql/mutations/create_post.rb. The only significant difference is that it requires id as an argument to update a specific post.

module Mutations
  class UpdatePost < Mutations::BaseMutation
    graphql_name 'UpdatePost'

    field :post, Types::PostType, null: true
    field :result, Boolean, null: true

    argument :id, ID, required: true
    argument :title, String, required: false
    argument :description, String, required: false

    def resolve(**args)
      post = Post.find(args[:id])
      post.update(title: args[:title], description: args[:description])
      {
        post: post,
        result: post.errors.blank?
      }
    end
  end
end

Testing with GraphiQL

Make a request like the code below and check the result.

mutation {
  updatePost(
    input:{
      id: 1
      title: "Updated"
      description: "UPdated"
    }
  ){
    post {
      id
      title 
      description
    }
  }
}

################ Result #####################
{
  "data": {
    "updatePost": {
      "post": {
        "id": 1,
        "title": "Updated",
        "description": "UPdated"
      }
    }
  }
}

Mutation Delete

Do pretty much the same as you did to create create and update mutations.
Run the command below and modify the generated file.

$ rails g graphql:mutation DeletePost

This time, all you need is one argument id to delete a post!

# graphql/mutations/delete_post.rb
module Mutations
  class DeletePost < Mutations::BaseMutation
    graphql_name 'DeletePost'

    field :post, Types::PostType, null: true
    field :result, Boolean, null: true

    argument :id, ID, required: true

    def resolve(**args)
      post = Post.find(args[:id])
      post.destroy
      {
        post: post,
        result: post.errors.blank?
      }
    end
  end
end

Testing with GraphiQL

Make a request like the code below and check the result.

mutation {
  deletePost(
    input:{
      id: 1
    }
  ){
    post {
      id
      title 
      description
    }
  }
}

################ Result #####################
{
  "data": {
    "posts": [
      {
        "id": 2,
        "title": "How to learn Ruby"
      },
      {
        "id": 3,
        "title": "title1"
      }]
  }
}

Connection fields(1)

Once you understand how types, queries and mutations work, it is easy to work with associations.
Let's make it able to retrieve comments that are posted on each post with the corresponding post.
First, create the comment model and set up the has_many association with the Post model and create some data to check the query later on.

$ rails g model Comment content:string post:references

# app/models/comment.rb
class Comment < ApplicationRecord
  belongs_to :post
end

# app/models/post.rb
class Post < ApplicationRecord
  has_many :comments, dependent: :destroy
end

# db/seeds.rb
Post.new.tap do |post|
  post.title = 'title'
  post.description = 'description'
  post.comments.build(content: 'comment1')
  post.save!
end

$ rake db:seed

Secondly, Create the comment type by running the command below.

$ rails g graphql:object Comment id:ID! content:String!

The command will create a file which looks like the code below.

# app/graphql/types/comment_type.rb
module Types
  class CommentType < Types::BaseObject
    description 'Comment'

    field :id, ID, null: false
    field :content, String, null: false
  end
end

Lastly, add the comments field to post type.

# app/graphql/types/post_type.rb
module Types
  class PostType < Types::BaseObject
    description 'Post'

    field :id, Int, null: false
    field :title, String, null: false
    field :description, String, null: false
    field :comments, [Types::CommentType], null: false 
  end
end

Testing with GraphiQL

Make a request like the code below and check the result.

{
  posts {
    id
    title
    comments {
      id
      content
    }
  }
}

################ Result #####################
{
  "data": {
    "posts": [
      {
        "id": "1",
        "title": "title",
        "comments": [
          {
            "id": "1",
            "content": "comment1"
          }
        ]
      }
    ]
  }
}

Connection fields(2)

Let's make it able to create a new comment.
First things first, run the command below to create CreateComment mutation and add that to /graphql/types/mutation_type.rb.

$ rails g graphql:mutation CreateComment

Next, add field :post, Types::PostType, null: false to app/graphql/types/comment_type.rb.

# app/graphql/types/comment_type.rb
module Types
  class CommentType < Types::BaseObject
    description 'Comment'
    field :id, ID, null: false
    field :content, String, null: false
    field :post, Types::PostType, null: false
  end
end

Lastly, modify app/graphql/mutations/create_comment.rb like the code below.

# app/graphql/mutations/create_comment.rb
module Mutations
  class CreateComment < Mutations::BaseMutation
    graphql_name 'CreateComment'

    field :comment, Types::CommentType, null: true
    field :result, Boolean, null: true

    argument :post_id, ID, required: true
    argument :content, String, required: true

    def resolve(**args)
      post = Post.find(args[:post_id])
      comment = post.comments.build(content: args[:content])
      comment.save
      {
        comment: comment,
        result: post.errors.blank?
      }
    end
  end
end

Testing with GraphiQL

Make a request like the code below and check the result.

mutation {
  createComment(
    input:{
      postId: 1
      content: "NEW COMMENT"
    }
  ){
    comment {
      id
      content
      post {
        id
        title
        comments {
          id
          content
        }
      }
    }
  }
}

################ Result #####################
{
  "data": {
    "createComment": {
      "comment": {
        "id": "2",
        "content": "NEW COMMENT",
        "post": {
          "id": "1",
          "title": "title",
          "comments": [
            {
              "id": "1",
              "content": "comment1"
            },
            {
              "id": "2",
              "content": "NEW COMMENT"
            }
          ]
        }
      }
    }
  }
}

Utilizing resolvers directory

First, Create app/graphql/resolvers/ and create app/graphql/resolvers/base_resolver.rb.

module Resolvers
  class BaseResolver < GraphQL::Schema::Resolver
  end
end

Secondly, create app/graphql/resolvers/query_type and also create posts_resolver.rb and post_resolver.rb under the directory.

-- graphql
   -- resolvers
      -- query_type
       - posts_resolver.rb
       - post_resolver.rb

Modify posts_resolver.rb and post_resolver.rb llike the code below respectively.

# app/graphql/resolvers/query_type/posts_resolver.rb

module Resolvers
  module QueryType
    class PostsResolver < Resolvers::BaseResolver
      type [Types::PostType], null: false

      def resolve(**_args)
        Post.all
      end
    end
  end
end

# app/graphql/resolvers/query_type/post_resolver.rb

module Resolvers
  module QueryType
    class PostResolver < Resolvers::BaseResolver
      type Types::PostType, null: false
      argument :id, ID, required: false

      def resolve(**args)
        Post.find(args[:id])
      end
    end
  end
end

Lastly, connect them with the query_type.rb.
You can use the same requests to retrieve posts and each post now!

# app/graphql/types/query_type.rb

module Types
  class QueryType < Types::BaseObject
    field :posts, resolver: Resolvers::QueryType::PostsResolver
    field :post, resolver: Resolvers::QueryType::PostResolver
  end
end