Prerequisites

System Requirements

Before installing Quail, make sure your environment meets these requirements:

• Ruby >= 3.2.0
• Rails >= 7.0
• A working Rails application with ActiveRecord models
• The graphql gem (>= 2.0) installed automatically as a Quail dependency

If you already have a Rails app with models defined, you’re ready to go.

What is GraphQL?

If you’ve never worked with GraphQL before don’t worry; the concepts map directly to things you already know from Rails.

Instead of defining multiple REST endpoints (/articles, /articles/:id, /articles/:id/comments), GraphQL exposes a single endpoint where the client specifies exactly what data it needs. Think of it as letting the client write its own SELECT statement, but safely constrained by a schema you define.

Key Concepts (in Rails Terms)

GraphQL Concept	Rails Analogy
Schema	routes.rb what’s available
Types	serializers or presenters; the shape of data
Queries	GET controller actions
Mutations	POST, PATCH, DELETE controller actions
Subscriptions	ActionCable channels

A Simple Example

Here’s a GraphQL query that fetches an article with its author name:

query {
  article(id: "1") {
    title
    body
    author {
      name
    }
  }
}

The response comes back as JSON matching the shape you asked for:

{
  "data": {
    "article": {
      "title": "Getting Started with Quail",
      "body": "Quail makes GraphQL feel like Rails...",
      "author": {
        "name": "Taylor"
      }
    }
  }
}

No over-fetching, no under-fetching. The client gets exactly what it requested.

GraphQL and REST: Not Either/Or

GraphQL is not a wholesale replacement for RESTful APIs. Many production applications use both side by side. REST for simple CRUD endpoints, webhooks, or third-party integrations, and GraphQL for client-facing queries where flexible data fetching matters most. You can introduce Quail incrementally alongside your existing REST controllers without rewriting anything.

For a deeper dive into GraphQL fundamentals, the official GraphQL introduction is an excellent resource.

How Quail Fits In

Quail sits between your Rails models and graphql-ruby. You define resource classes with a simple DSL, and Quail generates the GraphQL types, queries, mutations, and subscriptions for you.

You don’t need to be a GraphQL expert to use Quail. The DSL abstracts away the complexity of graphql-ruby’s class hierarchy; you declare what you want exposed, and Quail handles the wiring. For advanced use cases (custom resolvers, complex authorization), understanding GraphQL fundamentals helps, but it’s not required to get started.

If you know how to define a Rails model and write a serializer, you already have the mental model you need.