GraphQL is an open source query language created by Facebook. It is a powerful tool that you can use for building your API. It is not a silver bullet but it can definitely help you solve some challenges like getting many resources in a single request. It does not suffer from over-fetching or under-fetching of data and in opposition to the REST API, GraphQL is strongly typed and it is not versioned. In this article, I would like to show you how to setup a Ruby On Rails application with PostgreSQL and GraphQL.
Setup
I assume that you have the latest Ruby version available on your computer. Ideally, you installed it through asdf or rvm. I also assume that you have created a gemset for your application. The only other thing that you need is a running PostgreSQL.
As usual with new Rails applications, you have to start with installing a bundler
gem install bundler
and then install the latest rails with this command (which can take a while)
bundle install rails
Finally, we will generate a new rails project
rails new graphql_test --database=postgresql
Remember to set up database.yml
and then create a database with
rake db:create
Adding GraphQL
We are going to use the graphql-ruby gem so in your Gemfile
you have to add
gem 'graphql'
and follow it with bundle install
The next command will be
rails generate graphql:install
which will do a few things:
- add this line to config/routes.rb
As you probably know, in GraphQL API we define one endpoint which you can use for retrieving or changing data. As you can see this endpoint will be available for us in /graphql path but remember that you have to use the POST method to access it.
- creates our graphQL controller
app/controllers/graphql_controller.rb
which will be handling all queries in the execute method:
worth noticing is the way we gather parameters for GraphqlTestSchema.execute
method.
- a lot of base types:
- base_enum
- base_input_object
- base_interface
- base_object
- base_scalar
- base_union
- mutation_type
- query_type
we will be using them for constructing mutations, queries, interfaces, and other types
- adds
gem 'graphiql-rails', group: :development
to your Gemfile which mounts the GraphiQL IDE that you can use during development. You will have to dobundle install
one more time to use it. In routes.rb you will probably notice those lines of codes
Thanks to them you will be able to use /graphiql
path to easily test your endpoint locally.
- adds
app/graphql/store_manager_schema.rb
that will be you entry point for the whole application
Preparing models and data
Let’s start with those:
bin/rails generate model Author first_name:string last_name:string date_of_birth:date --no-test-framework
bin/rails generate model Book title:string author:references publication_date:integer genre:string --no-test-framework
They will generate migrations that we can run with rake db:migrate
. They will also generate models. The only thing that we have to do is add
to app/models/author.rb
.
fill in db/seeds.rb
with:
and run seeds with rake db:seed
Generates types
As I mentioned before, GraphQL is strongly typed which means that if we want to query for `Author` and `Book` we have to define types for them.
app/graphql/types/author_type.rb
app/graphql/types/book.rb
We have a convention that at the top we are adding complex types, followed by ID and at the end simple types like Integer, String etc. As you can see, we are using an enum for the genre. We define enums in a separate directory. app/graphql/types/enums/genre.rb
Defining queries
app/graphql/types/enums/genre.rb
We defined 4 different queries. Two for collections books
and authors
, and two for finding book
and author
using ID. This is actually everything to be able to perform nested queries like:
or
Summary
As you can see, starting a GraphQL project with Ruby On Rails is super easy, therefore, if this is a solution that will solve your problems you shouldn’t stick to REST API and give it a try. In the next articles, I will show you how to define mutations, add authentication, pagination and many more, so stay tuned.