Declaring, composing and executing GraphQL queries with ruby

A few weeks ago github released it’s GraphQL powered API and with that a ruby library for composing and executing GraphQL queries using ruby.

The example available on github repo is a rails example and so the writer thought for learning internals it would be good idea to experiment it with other ruby frameworks like Sinatra.

In this post we will use the GraphQL server we have built over a series of posts and a brand new Sinatra app together with the released ruby library to query the api server instead of using relay.

So, why use this library instead of relay or any other client side GraphQL library?

• Basically it’s simple to setup,
• You can use ruby and,
• No extra syntax or libraries to learn.

However, if you want to build an advanced app then perhaps using Relay or Apollo would make more sense. Another version of Relay called Relay2 is coming up pretty soon.

Lets begin….

Setup

Clone this Sinatra app repo to get started. It contains required gems, a basic asset pipeline and ERB views.

cd /to-your-work-directory
git clone git@github.com:gauravtiwari/graphql-sinatra-erb.git
cd graphql-sinatra-erb/
bundle install
 bundle exec rackup -p 5000

You can simply run the server at this stage but it will fail because we are missing a key piece i.e. a compatible GraphQL api server. Lets fix that by setting up the api endpoint to an environment variable.

You can export it like so,

export API_URL="https://relay-rails-blog.herokuapp.com/graphql"
export RACK_ENV="development"

Once done you can start the server and open it up in your browser by going to http://localhost:5000

Now, lets take a quick look at couple of internals involved.

Configuration

We have to configure the library for it to interact with any given GraphQL server. To do so, lets create a initialiser file that sets up API url and path for dumping schema.json. You can optionally pass things like authentication token by passing a block.

Note: Remember schema.json is manifest that contains a list of queries, fields and mutations type that are available on a GraphQL server.

That’s it. Now, we can use the declared client to send queries to initialised api server.

Declaring queries

Lets create a file called queries.rb inside initialisers folder and define two simple queries. You will notice they look exactly same as what we did in earlier posts with react and relay because the syntax is standard GraphQL.

We will use the initialised API client to parse and execute GraphQL queries and finally assign them to a ruby constant so, we can reference them later in our app.

Once the queries are setup, lets finally wire it up with our Sinatra app.

Executing queries

As you notice, the app itself is pretty simple and mostly standard Sinatra.

The only thing new is that query method, which is a helper method supplied by library to accept a query definition and any variables passed to send it to the server supplied in the initialiser.

So for our index action, IndexQuery constant is passed, which will be sent to the api server for execution. If the execution is successful it will return the data otherwise errors. Pretty Simple!

Resources

• GraphQL: Official GraphQL spec
• graphql-ruby : For defining GraphQL schema
• graphql-client: for declaring, composing and executing GraphQL queries
• Demo
• Code