Updated to the new class-based API, graphql gem version 1.8+

GraphQL has redefined the way we deal with APIs and endpoints. With the client being able to specify the fields it needs, development in the client could in one way be independent of the server changes, if a schema is predefined.

GraphQL + Sinatra — create a graphql endpoint in the lightweight micro framework.

We’ll see how to create a GraphQL server using the Sinatra framework in Ruby. In this example we will be creating the schema for a conference app, where you can add speakers and list them.

STEP 1: Create a Sinatra application

I wish there was a template to create a sinatra application using a cli. But there isn’t a lot of boilerplate files to create, so lets add it one-by-one.

We’ll be using puma as the server. Create an app.rb file which defines a basic sinatra app with a / route. Also a Gemfile is added and bundle install is run.

Next we need a rackup file config.ru so that puma will pickup the app as a rack application.

Running the puma server will serve your application at http://localhost:9292, and you should see the message ‘It Works!’.

bundle exec puma

Yay! The app is up.

STEP 2: Add JSON responses

For the server to respond to JSON, we add the sinatra-contrib gem, which adds a json helper. Change the app.rb file to respond to json.

Now our app contains just these files:

conference_app

|

├── Gemfile

├── Gemfile.lock

├── app.rb

└── config.ru

STEP 3: Add database connections and models with ActiveRecord

For talking to the database, we’ll use activerecord gem.

Add database configuration to connect to sqlite3

Also add a configuration file database.yml with the connection details and the sqlite3 gem for connecting to the sqlite database. app.rb needs changes to update this configuration.

Add Rakefile

Add the rake gem along with the Rakefile. This gives handy rake tasks for creating the table (migrations) and managing them.

bundle exec rake -T will display the added rake tasks.

Create the sqlite database, by running bundle exec rake db:create

Add a migration and model for Speaker object

Create a migration with the following rake command:

bundle exec rake db:create_migration NAME=create_speakers

Change the created migration file in db/migrate folder, to add the required database fields.

Run migrations with the rake task bundle exec rake db:migrate

Create a model file for Speaker, to access this table.

I’ve added a basic validation for the model. Read more on activerecord basics in the official basics introduction.

Add the pry gem for debugging and execute the following two statements in the pry console, for adding rows to the speakers table.

Use pry to create records for Speaker model.

require './app' Speaker.create(name: 'John', twitter_handle: 'johnruby', bio: 'This is John\'s bio', talk_title: 'How to bootstrap a sinatra application') Speaker.create(name: 'Jacob', twitter_handle: 'jacob-ruby', bio: 'This is Jacob\'s bio', talk_title: 'Introduction to graphql')



Add a /speakers endpoint

Create a new endpoint to show the list of speakers, as JSON.

STEP 4: Add graphql and define a query to list speakers

Now we have a sinatra app that connects to the database and shows a list of speakers as a JSON response. Now let’s add graphql and define a schema for speakers.

Add the graphql gem. https://github.com/rmosolgo/graphql-ruby. Read the documentation at http://graphql-ruby.org/.

Also the rack-contrib gem needs to be added so that the sinatra app can accept raw JSON payloads.

Add type, query and schema for graphql

Now we need to add a type for Speaker, also a query and a schema for GraphQL.

We need to then add a root query.

Define a schema for GraphQL.

The /graphql endpoint

We now need to have a POST endpoint for GraphQL.

GraphQL schema can be executed to give a GraphQL::Query::Result which can then be converted to JSON. app.rb needs change to include this endpoint.

Querying the endpoint

You can use the GraphiQL app or the Postman app to query the endpoint. Make sure that you have puma running and the server is up.

Querying the graphql endpoint in Postman

A JSON response like the below will be obtained.

That’s it for now. You have a GraphQL server up and running on sinatra, and you can query the endpoint to get a list of speakers with the fields defined in the GraphQL query.

Source Code

The source code is available at https://github.com/awinabi/sinatra-graphql

In Part 2 of this series, we’ll see how to add a mutation to add a new Speaker.