pushrax / graphql-ruby

Ruby implementation of Facebook's GraphQL

graphql

Overview

• Install the gem:

  # Gemfile
  gem 'graphql'

  $ bundle install
  

• Declare types & build a schema:

  # Declare a type...
  PostType = GraphQL::ObjectType.new do |t, types, field|
    t.name "Post"
    t.description "A blog post"
    t.fields({
      id:       field.build(type: !types.Int)
      title:    field.build(type: !types.String),
      body:     field.build(type: !types.String),
      comments: field.build(type: types[!CommentType])
    })
  end
  
  # ...and a query root
  QueryType = GraphQL::ObjectType.new do |t, types, field, arg|
    t.name "Query"
    t.description "The query root of this schema"
    t.fields({
      post: GraphQL::Field.new do |f|
        f.arguments(id: arg.build(type: !types.Int))
        f.resolve -> (object, args, context) {
          Post.find(args["id"])
        }
      end
    })
  end
  
  # Then create your schema
  Schema = GraphQL::Schema.new(query: QueryType, mutation: nil)

  See also:

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

• Execute queries:

  query = GraphQL::Query.new(Schema, query_string)
  result_hash = query.result
  # {
  #   "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

To Do:

• Validations:
  • Implement validations:
    • Fragment spreads are possible
      • In object scope, object-typed fragments are the same type
      • In object scope, abstract-typed fragments fit that object
      • In abstract scope, object-typed fragments fit that type
      • In abstract scope, abstract-typed fragments must share a type
    • everything in Variables
• directives:
  • @skip has precedence over @include
  • directives on fragments: http://facebook.github.io/graphql/#sec-Fragment-Directives
• Support any "real" value for enum, not just stringified name (see Character::EPISODES in demo)
• field merging (graphql/graphql-js#19 (comment))
• no such thing as multiple operations in one document?
• Code clean-up
  • Unify unwrapping types (It's on TypeKind but it's still not right)
  • de-dup stringify keys logic in Field and ObjectType and Directive

Goals:

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