chollier / graphql-ruby

Ruby implementation of Facebook's GraphQL

graphql

A Ruby implementation of GraphQL.

• Guides

  • Introduction
  • Defining Your Schema
  • Executing Queries
  • Testing

• API Documentation

Installation

Install from RubyGems by adding it to your Gemfile, then bundling.

# Gemfile
gem 'graphql'

$ bundle install

Overview

Declare types & build a schema

# Declare a type...
PostType = GraphQL::ObjectType.define do
  name "Post"
  description "A blog post"

  field :id, !types.ID
  field :title, !types.String
  field :body, !types.String
  field :comments, types[!CommentType]
end

# ...and a query root
QueryType = GraphQL::ObjectType.define do
  name "Query"
  description "The query root of this schema"

  field :post do
    type PostType
    argument :id, !types.ID
    resolve -> (obj, args, ctx) { Post.find(args["id"]) }
  end
end

# Then create your schema
Schema = GraphQL::Schema.new(
  query: QueryType,
  max_depth: 8,
)

See also:

• the test schema
• graphql-ruby-demo for an example schema on Rails

Execute queries

Execute GraphQL queries on a given schema, from a query string.

result_hash = Schema.execute(query_string)
# {
#   "data" => {
#     "post" => {
#        "id" => 1,
#        "title" => "GraphQL is nice"
#     }
#   }
# }

See also:

• query_spec.rb for an example of query execution.
• queries_controller.rb for a Rails example
• Try it on heroku

Use with Relay

If you're building a backend for Relay, you'll need:

• A JSON dump of the schema, which you can get by sending GraphQL::Introspection::INTROSPECTION_QUERY
• Relay-specific helpers for GraphQL like Connections, node fields, and global ids. Here's one example of those: graphql-relay

Getting Started Tutorials

Series: Building a blog in GraphQL and Relay on Rails

1. Introduction: https://medium.com/@gauravtiwari/graphql-and-relay-on-rails-getting-started-955a49d251de
2. Part1: https://medium.com/@gauravtiwari/graphql-and-relay-on-rails-creating-types-and-schema-b3f9b232ccfc
3. Part2: https://medium.com/@gauravtiwari/graphql-and-relay-on-rails-first-relay-powered-react-component-cb3f9ee95eca

Tutorials

1. https://medium.com/@khor/relay-facebook-on-rails-8b4af2057152
2. https://blog.jacobwgillespie.com/from-rest-to-graphql-b4e95e94c26b#.4cjtklrwt
3. http://mgiroux.me/2015/getting-started-with-rails-graphql-relay/
4. http://mgiroux.me/2015/uploading-files-using-relay-with-rails/

Goals

• Implement the GraphQL spec & support a Relay front end
• Provide idiomatic, plain-Ruby API with similarities to reference implementation where possible
• Support Ruby on Rails and Relay

Getting Involved

• Say hi & ask questions in the #ruby channel on Slack or on Twitter!
• Report bugs by posting a description, full stack trace, and all relevant code in a GitHub issue.
• Features & patches are welcome! Consider discussing it in an issue or in the #ruby channel on Slack to make sure we're on the same page.
• Run the tests with rake test or start up guard with bundle exec guard.

Related Projects

• graphql-ruby + Rails demo (src / heroku)
• graphql-batch, a batched query execution strategy
• graphql-parallel, an asynchronous query execution strategy
• Example Relay support in Ruby
• graphql-libgraphqlparser, bindings to libgraphqlparser, a C-level parser.

To Do

• Interface's possible types should be a property of the schema, not the interface
• Type lookup should be by type name (to support reloaded constants in Rails code)
• Add a complexity validator (reject queries if they're too big)
• Add docs for shared behaviors & DRY code
• Revamp the fixture Schema to be more useful (better names, more extensible)
• Fix when a field's type is left out field :name, "This is the name field"
• Subscriptions
  • This is a good chance to make an Operation abstraction of which query, mutation and subscription are members
  • For a subscription, graphql would send an outbound message to the system (allow the host application to manage its own subscriptions via Pusher, ActionCable, whatever)