graphql-preview

GraphQLPreview

Easily toggle parts of a GraphQL schema on.

Installation

Add this line to your application's Gemfile:

gem 'graphql-preview'

And then execute:

$ bundle

Or install it yourself as:

$ gem install graphql-preview

Usage

The basic premise of this gem is to provide an easier interface to toggling parts of a GraphQL schema. You define a single class that contains all the definitions for how your toggler should behave, and this gem will handle the flipping for you.

The easiest use case to imagine for this gem is to think of something like a public API preview. Perhaps you want to be able to expose certain objects or fields if and only if a client provides a specific Accept header. This gem will help you do that!

Class definition

To get started, define a class that inherits from GraphQLPreview::SchemaModification. This class can be given various properties, but the two most important are toggled_by and toggled_on:

class TestPreview < GraphQLPreview::SchemaModification
  # A human-readable name of your preview
  title "TestPreview"
  # A description of your preview
  description "Enable various library items"

  # A symbol that uniquely identifies this preview -- explained below
  toggled_by :enabled_library

  # A date defining when this preview was announced, with an optional URL announcing it
  announced_on Date.new(2017, 11, 1), url: "http://example.com"

  # A date defining when this preview was updated, with an optional URL announcing it
  updated_on Date.new(2017, 11, 2), url: "http://example.com"
  # You can have more than one of these!
  updated_on Date.new(2017, 11, 3), url: "http://example.com"

  # The parts of your GraphQL schema you want toggled by this preview
  toggled_on [
    "Author", # an object
    "ExtraInfo", # an interface,
    "Author.socialSecurityNumber", # a field
    "Book.author.includeMiddleInitial", # an argument
    "Likeable", # a union,
    "Cover", # an enum
    "Cover.DIGITAL", # an enum value
    "BookOrder", # an input object
    "Mutation.addLike", # a mutation
  ]
end

Toggling the preview on your schema

This gem introduces a new method to apply on your schema, enabled_previews. It takes an array, and you should pass in the list of preview classes you want enabled on your schema. For example:

class Schema < GraphQL::Schema
  query(query_type)
  enabled_previews [
    TestPreview
  ]
end

If you are using graphql-ruby's .define DSL a similar API is provided:

GraphQL::Schema.define do
  query(query_type)
  enabled_previews [
    TestPreview
  ]
end

Passing information to Schema.execute

After your preview class is configured, you'll need to make two minor changes to the way the schema is executed.

First, ensure that your context object has a key called schema_previews. Within this key, you'll provide an array of symbols that identify which previews you want enabled. For example:

context = { schema_previews: [:enabled_library] }

Next, simply pass in the GraphQLPreview::Mask class to the except kwarg.

Putting it all together, this looks like:

Schema.execute(query, context: context, except: GraphQLPreview::Mask)

It's up to you to decide how to determine the array in context[:schema_previews]. It could be based on the Accept header, some random Flipper percentage, or anything else!