Building an api with graphql and rails


Published 3 months ago

Image from [fiver]

As you all know, Rails is very popular for creating a web application in a short amount of time. Today, developers tend to separate concerns in their application by creating an API for the backend and consume it with any library of their choice.

Most of you must have heard of GraphQL: This definition from explains it all:

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.
Table of contents
# Prerequisites
# Project Setup
# Models
# Queries
# Mutations
# Conclusion
# Prerequisites

Before we begin, make sure you have ruby version ≥ 2.2 and rails version ≥ 5 installed on your local machine. 

If your ruby version is not up-to-date, you can update with a ruby version manager such as rvm or rbenv

$ rvm install "ruby-2.4.6"
$ rbenv install 2.4.6## You can update rails by running
$ gem update rails
That's all you need, you are good to start this awesome journey of building a simple GraphQL API with Rails.

# Project Setup

For this tutorial, you are expected to have the following tools:

  • Postgres Database
  • An Editor
Let's run rails in the command line to create all the files and folders we need for a basic Rails application using Postgres database.

$ rails new todo-app --database=postgresql
$ cd todo-app
To create a graphql application with rails, we will need to add a gem called graphql. Add this gem to your Gemfile.

# Gemfile
gem 'graphql'
Install the gem by running:

$ bundle install
Hurray, the gem is now installed successfully. To create all files and folders needed for a GraphQL API, run:

$ rails generate graphql:install
Running this will add graphiql-rail gem to your Gemfile. This gem will allow us to interact with the API.

# Database setup

To connect our application to the Postgres database, go to config/database.yml file and add your Postgres username and password to both test environment and development environment.

  <<: *default
  database: todo_app_development
  <<: *default
  database: todo_app_development
Create the database by running: 

$ rails db:create
Finally, run the server by running:

$ rails server
Visit this route localhost:3000/graphiql and you should see a graphql client which can be used to place a request to our graphql server.


# Models

For this todo application, we will create a todos table that has two fields: title and description. Create the model by running:

$ rails generate model Todo title:string description:text
You can validate the title and the description field by making sure it is always specified before entering the database. Navigate to models/todos.rb and add rails validation. 

class Todo < ApplicationRecord
    validates :title, presence: true
    validates :description, presence: true
Run migration by running:

$ rails db:migrate
Let’s add some data into our database by running rails console using:

$ rails console
>- Todo.create(title: 'Sample title', description: 'Sample Description')
Rails console

GraphQL schema has three special root types, these are called Query, Mutation and Subscription

  • Queries: are GraphQL features that enable data fetching from the database. It works like a GET call in Rest APIs.
  • Mutations: are GraphQL features that allow a client sends data to the database. It works like POST, PUT and DELETE in REST API’s.
  • Subscriptions: Subscriptions are a GraphQL feature that allows a server to send data to its clients when a specific event happens. Subscriptions are usually implemented with WebSockets. [Action Cable]
# Query

Let's create our first query to get all todos from the database. 

Create a new type for todos by creating a new file: app/graphql/types/todo_type.rb. 

#app/graphql/types/todo_type.rbmodule Types
  class TodoType < Types::BaseObject
    field :title, String, null: false
    field :description, String, null: false
It inherits from BaseObject, checkout out app/graphql/types/base_object.rb. It inherits from Graphql schema type instead of writing GraphQL::Schema::Object, just inheriting from BaseObject gives us all attributes needed to create an object Schema.

The next step is to create a query type that will be used to get all todos. Go to app/graphql/types/query_type.rb. Add a new field to the query type. :all_todos to get all our todos.

# app/graphql/types/query_typefield :all_todos, [TodoType], null: false,
    description: "Returns all todos"
def all_todos
The [TodoType] is added because we are expecting a list of todos. 

Over to the browser and write a query like this:

query {
  allTodos {
With this, it will return all the todos in the database, we can choose to skip the title and ask for the description and vice-versa.

# Mutation

The next step is to add a mutation to create todos. Before that, let’s create a BaseMutationclass that inherits from GraphQL::Schema::Mutation. This will enable us to inherit from BaseMutation going forward.

Create a new file called base_mutation.rb in apps/graphql/mutations folder. Add this code:

module Mutations
  class BaseMutation < GraphQL::Schema::Mutation
    null false
Fine, that is out of the way. Let’s create a mutation to add todo. To do this we will create a file called add_todo.rb in the mutations folder and add this code.

module Mutations
  class AddTodo < BaseMutation
    argument :title, String, required: true
    argument :description, String, required: true

    type Types::TodoType

    def resolve(title: nil, description: nil)
      Todo.create!(title: title, description: description)
    rescue ActiveRecord::RecordInvalid => e
This code add AddTodo mutation specifying the argument needed and the type that will be returned.

There is a rescue block in the mutation code. GraphQL in rails has an error handling block which is

Add the created mutation to mutation type so it will be accessible to the client.

# app/graphql/types/mutation_type.rb
module Types
  class MutationType < Types::BaseObject
     field :add_todo, mutation: Mutations::AddTodo
Test it on your browser by creating some todos using this query.

mutation {
  addTodo(title: "New Todo", description: "I will eat rice") {
Hurray!!!!!, we have created some todos and also know how to get todos from our database through the use of queries. I will be writing another article for performing authorization and authentication to ensure a user can log in, delete and also update their todos.

With this article, I believe you can create a simple API with Rails and GraphQL.

Thanks for reading.