graphql

Create a GraphQL interface by implementing nodes and calls, then running queries.

Example Implementation

See test implementation in /spec/support/dummy_app/nodes.rb
See graphql-ruby-demo with Rails on github or heroku

Usage

Create a GraphQL interface:

Implement nodes that wrap objects in your application
Implement calls that expose those objects (and may mutate the application state)
Execute queries on the system.

Nodes

Nodes are delegators that wrap objects in your app. You must whitelist fields by declaring them in the class definition.

class FishNode < GraphQL::Node
  exposes "Fish"
  cursor(:id)
  field.number(:id)
  field.string(:name)
  field.string(:species)
  # specify an `AquariumNode`:
  field.aquarium(:aquarium)
end

You can also declare connections between objects:

class AquariumNode < GraphQL::Node
  exposes "Aquarium"
  cursor(:id)
  field.number(:id)
  field.number(:occupancy)
  field.connection(:fishes)
end

You can make custom connections:

class FishSchoolConnection < GraphQL::Connection
  type :fish_school # now it is a field type
  call :largest, -> (prev_value, number)  { fishes.sort_by(&:weight).first(number.to_i) }

  field.number(:count) # delegated to `target`
  field.boolean(:has_more)

  def has_more
    # the `largest()` call may have removed some items:
    target.count < original_target.count
  end
end

Then use them:

class AquariumNode < GraphQL::Node
  field.fish_school(:fishes)
end

And in queries:

aquarium(1) {
  name,
  occupancy,
  fishes.largest(3) {
      edges {
        node { name, species }
      },
      count,
      has_more
    }
  }
}

Calls

Calls selectively expose your application to the world. They always return values and they may perform mutations.

Calls declare returns, declare arguments, and implement #execute!.

This call just finds values:

class FindFishCall < GraphQL::RootCall
  returns :fish
  argument.number(:id)
  def execute!(id)
    Fish.find(id)
  end
end

This call performs a mutation:

class RelocateFishCall < GraphQL::RootCall
  returns :fish, :previous_aquarium, :new_aquarium
  argument.number(:fish_id)
  argument.number(:new_aquarium_id)

  def execute!(fish_id, new_aquarium_id)
    fish = Fish.find(fish_id)

    # context is defined by the query, see below
    if !context[:user].can_move?(fish)
      raise RelocateNotAllowedError
    end

    previous_aquarium = fish.aquarium
    new_aquarium = Aquarium.find(new_aquarium_id)
    fish.update_attributes(aquarium: new_aquarium)
    {
      fish: fish,
      previous_aquarium: previous_aquarium,
      new_aquarium: new_aquarium,
    }
  end
end

Queries

When your system is set up, you can perform queries from a string.

query_str = "find_fish(1) { name, species } "
query     = GraphQL::Query.new(query_str)
result    = query.as_result

result
# {
#   "1" => {
#     "name" => "Sharky",
#     "species" => "Goldfish",
#   }
# }

Each query may also define a context object which will be accessible at every point in execution.

query_str = "move_fish(1, 3) { fish { name }, new_aquarium { occupancy } }"
query_ctx = {user: current_user, request: request}
query     = GraphQL::Query.new(query_str, context: query_ctx)
result    = query.as_result

result
# {
#   "fish" => {
#     "name" => "Sharky"
#   },
#   "new_aquarium" => {
#     "occupancy" => 12
#   }
# }

You could do something like this inside a Rails controller.

To Do:

testing with JSON args
Make root calls plain ol' calls, on the root?
Make fields like calls with no args?
improve debugging experience
build nodes for Date, DateTime, Time, Hash
How do you express failure? HTTP response? errors key?
Handle blank objects in nested calls (how? wait for spec)
Implement calls as arguments
double-check how to handle pals.first(3) { count }
Implement call argument introspection (wait for spec)