graphql

A Ruby implementation of GraphQL.

Guides
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 -&gt; (obj, args, ctx) { Post.find(args["id"]) }
  end
end

# Then create your schema
Schema = GraphQL::Schema.define do
  query QueryType
  max_depth 8
end

Execute queries

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

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

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, see GraphQL::Relay

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

Code

graphql-ruby + Rails demo (src / heroku)
graphql-batch, a batched query execution strategy
graphql-libgraphqlparser, bindings to libgraphqlparser, a C-level parser.

Blog Posts

Building a blog in GraphQL and Relay on Rails Introduction, Part 1, Part 2
https://medium.com/@khor/relay-facebook-on-rails-8b4af2057152
https://blog.jacobwgillespie.com/from-rest-to-graphql-b4e95e94c26b#.4cjtklrwt
http://mgiroux.me/2015/getting-started-with-rails-graphql-relay/
http://mgiroux.me/2015/uploading-files-using-relay-with-rails/

To Do

StaticValidation improvements
- Use catch-all type/field/argument definitions instead of terminating traversal
- Reduce ad-hoc traversals?
- Validators are order-dependent, is this a smell?
- Tests for interference between validators are poor
- Maybe this is a candidate for a rewrite?
Add Rails-y argument validations, eg less_than: 100, max_length: 255, one_of: [...]
- Must be customizable
Relay:
- GlobalNodeIdentification.to_global_id should receive the type name and object, not id. (Or, maintain the “type_name, id in, type_name, id out” pattern?)
- Reduce duplication in ArrayConnection / RelationConnection
- Improve API for creating edges (better RANGE_ADD support)
- If the new edge isn’t a member of the connection’s objects, raise a nice error
Missing Enum value should raise a descriptive error, not “key not found”
args should whitelist keys – if you request a key that isn’t defined for the field, it should 💥

Modules

Classes