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!