Building APIs with GraphQL and Ruby on Rails

GraphQL is a query language for APIs and a server environment for fulfilling those queries. It uses the type system defined according to your specific requirements. GraphQL was developed by Facebook in 2012, it is considered by many to be the future of APIs. 

I am interested in building APIs using GraphQL with Ruby on Rails, and that’s what I’m going to do. GraphQL is not tied to any programming language or technology, that’s why it can be used with different platforms for the development of the APIs.

GraphQL is not just for building new APIs but also for improving and expanding the existing ones.

GraphQL defines the types and their fields and provides the tools to work the fields of each type (mutations, resolvers, and so on). GraphQL supports reading, mutating, and real-time updates.

Here’s the example of a user list query:

{
	allUsers {
	  name,
	  email
	}
}

The result must be in JSON:

{
  "data": {
    "allUsers": [
      {
        "name": "Mickey",
        "email": "mickey@api.com"
      },
    ]
  }
}

To be honest, GraphQL is a huge topic and I’m making no claims I can cover it all here. However, to illustrate the practical use and some of the basic features of GraphQL, I’ll go with an example below. In it, I will show the implementation of an  API with the following features:

  • Getting the list of articles
  • Getting a specific article
  • Creating an article
  • Deleting an article

⚠️ Note: these examples are purely demonstrational and should not be used in live projects.

Building APIs with GraphQL and Ruby on Rails

  1. Create a new project:
gem install bundler
gem install rails

rails new example-graphql -v '5.2.0'

cd example-graphql
  1. Add GraphQL into the Gemfile:
echo "gem 'graphiql-rails', group: :development" >> Gemfile
echo "gem 'graphql'" >> Gemfile

3. Launch:

bundle install
rails generate graphql:install
rails server

4. Go to http://localhost:3000/graphiql to see the  Web IDE:

Building APIs with GraphQL and Ruby on Rails | Shakuro
  1. Click the Docs to see the documentation generated for our queries.

Queries

  1. Create an article model:
rails g model article title:string description:text

2. Add validation to the app/models/article.rb model:

class Article < ApplicationRecord
 validates :title, :description, presence: true
end

3. Apply changes:

rake db:migrate

4. Populate the database with data:

rails s
Article.create!(title: 'Title1', description: 'Description1')
Article.create!(title: 'Title2', description: 'Description2')
exit

5. Create the new  Article type:

app/graphql/types/article_type.rb
class Types::ArticleType < Types::BaseObject
 graphql_name 'Article'
 field :id, ID, null: false
 field :title, String, null: false
 field :description, String, null: false
end

6. Update  QueryType:

app/graphql/types/query_type.rb
module Types
  class QueryType < Types::BaseObject
    field :allArticles, [ArticleType], null: false

    field :article, ArticleType, null: true
      argument :id, ID, required: true
    end

    def all_articles
      Article.all
    end
  1. Get the list of articles:
Building APIs with GraphQL and Ruby on Rails | Shakuro

Or get the information about a specific article:

Building APIs with GraphQL and Ruby on Rails | Shakuro

Mutations

GraphQL allows you to easily modify the data by means of mutation.

Mutations are special fields which do not include the task of getting the data or making computations. They are used to change the following app states by:

  • Creating, updating, and deleting database records.
  • Creating associations.
  • Cleaning the cache.
  • Working with files.

These actions are called “side effects”.

To make a record in the database, you need a new mutation. Create it with a built-in generator and the following command:

rails g graphql:mutation create_article

This will create a new file:

app/graphql/mutations/created_article.rb

Change it:

module Mutations
  class CreateArticle < GraphQL::Schema::RelayClassicMutation
    # TODO: define return fields
    # field :post, Types::PostType, null: false

    field :article, Types::ArticleType, null: false

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


    # TODO: define resolve method
    # def resolve(name:)
    #   { post: ... }
    # end
    def resolve(title:, description:)
      article = Article.create!(title: title, description: description)

      {
        article: article
      }

    end
  end
end

Define the mutation field:

app/graphql/types/mutation_type.rb
module Types
  class MutationType < Types::BaseObject
    field :createArticle, mutation: Mutations::CreateArticle
  end
end

Now you can create an article:
Building APIs with GraphQL and Ruby on Rails | ShakuroSimilarly, you can delete the objects through mutations. Here’s how:

  1. Create a new mutation:
rails g graphql:mutation remove_article

This will update the existing mutation type:

app/graphql/types/mutation_type.rb
module Types
  class MutationType < Types::BaseObject
    field :removeArticle, mutation: Mutations::RemoveArticle
    # TODO: remove me
    # field :test_field, String, null: false,
    #   description: "An example field added by the generator"
    # def test_field
    #   "Hello World"
    # end
    field :createArticle, mutation: Mutations::CreateArticle
  end
end

Edit the new file:

app/graphql/mutations/remove_article.rb
module Mutations
  class RemoveArticle < GraphQL::Schema::RelayClassicMutation
    # TODO: define return fields
    # field :post, Types::PostType, null: false

    field :article, Types::ArticleType, null: false

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


    # TODO: define resolve method
    # def resolve(name:)
    #   { post: ... }
    # end
    def resolve(id:)
      article = Article.find(id)
      article.destroy!

      { article: article }
    end
  end
end

The query will look like this:

Building APIs with GraphQL and Ruby on Rails | Shakuro

This is how you build APIs with GraphQL and Ruby on Rails. There’s a lot more to talk about and if you feel like exploring further, here are some sources:

graphql.org

wikipedia.org/wiki/GraphQL

graphql-ruby.org

Written by Sergey Kuznetsov
January 01, 2019

loading...