use GraphQL;
class Query
{
method hello(--> Str) { 'Hello World' }
}
my $schema = GraphQL::Schema.new(Query);
say $schema.execute('{ hello }').to-json;
"GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools." - Facebook Inc., http://graphql.org.
The GraphQL Language is described in detail at http://graphql.org which also includes the draft specification. This module is a Perl 6 server implementation of that specification (or will be once it is complete). The intent of this documentation isn't to fully describe GraphQL and its usage, but rather to describe that Perl implementation and how various functionality is accessible through Perl. This document will assume basic awareness of GraphQL and that standard.
GraphQL itself isn't a database, it is the interface between the client and whatever database or other data store you use. Constructing a GraphQL server consists of describing your API Schema consisting of a data structure of data Types, and connecting to subroutines or methods for Resolution of the actual data values. The Schema is the controller or orchestrator for everything. It performs two major functions, Validation to determine if a query is valid at all, and Execution, which makes calls to arbitrary code for Resolution to determine the resulting data structure. The GraphQL language also specifies Introspection which is essentially Resolution carried out by the Schema itself to describe itself.
The synopsis above describes the simplest GraphQL server possible. It consists of a single Type or Class called Query, with a single field in it called hello of type String, with a method attached to it that returns the string Hello World.
The schema is constructed by passing the Perl 6 class into the GraphQL::Schema's new() constructor. The example then passes in the simplest GraphQL query {hello}. Execution will call the hello() method and return the result in a GraphQL::Result structure that can then be converted into JSON with to-json() method which will return the result:
{
"data": {
"hello": "Hello World"
}
}
In a typical GraphQL Web server, the query would be HTTP POSTed to an endpoint at /graphql which would call GraphQL::Schema.execute() and send the resulting JSON string back to the requester.
Each of those steps will be described in more detail below.
This module currently supports three different styles for expressing GraphQL types for your GraphQL schema:
- Manual - You can construct each type by creating and nesting various
GraphQL::*objects.
For the "Hello World" example, it would look like this:
my $schema = GraphQL::Schema.new(
GraphQL::Object.new(
name => 'Query',
fieldlist => GraphQL::Field.new(
name => 'hello',
type => $GraphQLString,
resolver => sub { 'Hello World' }
)
)
);
- GraphQL Schema Language or GSL- The Perl 6 GraphQL engine includes a complete parser for the GraphQL Schema Language described in detail at http://graphql.org. It is important to note that this is a different language from the GraphQL Query language which will be described later. There is also a handy cheat sheet for the GSL at https://github.com/sogko/graphql-shorthand-notation-cheat-sheet/.
For the "Hello World" example, it would look like this:
my $schema = GraphQL::Schema.new('type Query { hello: String }',
resolvers => { Query => { hello => sub { 'Hello World' } } });
Note that while the schema type descriptions are provided in the GSL, the resolving functions for each field must be separately supplied in a two level hash with the names of each Object Type at the first level, and Field at the second level.
- Direct Perl Classes - You can also simply pass in Perl 6 classes directly. A matching schema is constructed by examining the classes with the Perl language Metamodel for introspection. Given the GraphQL type restrictions, not everything you can express in Perl will result in a valid Schema, so it is important to use only the types as described below. Also restrict the names of attributes and methods to the alpha-numeric and '_'. (No fancy unicode names, or kebab-case names.)
For the "Hello World" example, it looks like this:
class Query
{
method hello(--> Str) { 'Hello World' }
}
my $schema = GraphQL::Schema.new(Query);
Under the hood, the Schemas all look the same, regardless of which style you use to construct them. The later two options are just additional syntactic sugar to make things easier. You can also mix and match, making some types one way and some another and everything will still work fine.
GraphQL is a strongly, staticly typed language. Every type must be defined precisely up front, and all can be checked during validation phase prior to execution.
The Perl Class hierarchy for GraphQL Types includes these:
-
GraphQL::Type (abstract, not to be used directly, only inherited
-
GraphQL::Scalar
-
GraphQL::String
-
GraphQL::Int
-
GraphQL::Float
-
GraphQL::ID
-
GraphQL::EnumValue
-
GraphQL::List
-
GraphQL::Non-Null
-
GraphQL::InputValue
-
GraphQL::Field
-
GraphQL::Interface
-
GraphQL::Object
-
GraphQL::InputObjectType
-
GraphQL::Union
-
GraphQL::Enum
-
GraphQL::Directive
GraphQL::Field and GraphQL::EnumValue are Deprecatable
They get two extra public attributes $.isDeprecated Bool, default False, and $.deprecationReason Str.
They also get the method .deprecate(Str $reason), which defaults to "No longer supported."
In GSL, you can also deprecate with the directive @deprecate or @deprecate(reason: "something"). More on directives below.
GraphQL::Object and GraphQL::Interface both include a role HasFields that give them a @.fieldlist array of GraphQL::Fields, a method .field($name) to look up a field, and a method .fields(Bool :$includeDeprecated) that will return the list of fields. Meta-fields with names starting with "__" are explicitly not returned in the .fields() list, but can be requested with .field().
This is the main GraphQL type base class. It has public attributes $.name and $.description. It isn't intended to be used directly, it is just the base class for all the other Types.
The description field can be explicitly assigned in the creation of each GraphQL::Type.
In GSL, you can set the description field by preceding the definition of types with comments:
# Description for mytype
type mytype {
# Description for myfield
myfield: Str
}
In Perl, the description field is set from the Meto-Object Protocol $obj.WHY method which by default will be set automatically with Pod declarations. e.g.
#| Description for mytype
class mytype {
#| Description for myfield
has Str $.myfield
}
Serves as the base class for scalar, leaf types. It adds the method .kind() = 'SCALAR';
There are several core GraphQL scalar types that map to Perl basic scalar types:
| GraphQL Type | Perl Type Class | Perl Object Instance | Perl Type |
| String | GraphQL::String | $GraphQLString | Str |
| Int | GraphQL::Int | $GraphQLInt | Int |
| Float | GraphQL::Float | $GraphQLFloat | Num |
| Boolean | GraphQL::Boolean | $GraphQLBoolean | Bool |
| ID | GraphQL::ID | $GraphQLID | ID (subset of Cool) |
The Perl Object Instances are just short hand pre-created objects that can be used since those types are needed so frequently.
For example, GraphQL::String.new creates a String type, but you can just use $GraphQLString which is already made.
You can create your own additional scalar types as needed:
my $URL = GraphQL::Scalar.new(name => 'URL');
or in GSL:
scalar URL
Core String type, maps to Perl type Str.
You can create your own:
my $String = GraphQL::String.new;
or just use $GraphQLString.
Core Int type, maps to Perl type Int.
You can create your own:
my $Int = GraphQL::Int.new;
or just use $GraphQLInt.
Core Float type, maps to Perl type Num.
You can create your own:
my $Float = GraphQL::Float.new;
or just use $GraphQLFloat.
Core Boolean type, maps to Perl type Bool.
You can create your own:
my $Boolean = GraphQL::Boolean.new;
or just use $GraphQLBoolean.
Core ID type, maps to Perl type ID which is a subset of Cool.
You can create your own:
my $ID = GraphQL::ID.new;
or just use $GraphQLID.
The individual enumerated values of an Enum, represented as quoted strings in JSON.
my $enumvalue = GraphQL::EnumValue.new(name => 'SOME_VALUE');
They can also be deprecated:
my $enumvalue = GraphQL::EnumValue.new(name => 'SOME_VALUE',
:isDeprecated,
reason => 'Just because');
or can be later deprecated:
$enumvalue.deprecate('Just because');
See GraphQL::Enum for more information about creating EnumValues.
.kind() = 'LIST', and has $.ofType with some other GraphQL::Type.
my $list-of-strings = GraphQL::List.new(ofType => $GraphQLString);
In GSL, Lists are represented by wrapping another type with square brackets '[' and ']'. e.g.
[String]
By default GraphQL types can all take on the value null (in Perl, Nil). Wrapping them with Non-Null disallows the null.
.kind() = 'NON_NULL'
my $non-null-string = GraphQL::Non-Null.new(ofType => $GraphQLString);
In GSL, Non-Null types are represented by appending an exclation point, '!'. e.g.
String!
To define a Perl class with a non-null attribute, both add the :D type constraint to the type, and also specify it as is required (or give it a default). To mark a type in a method as non-null, append with an exclamation point. e.g.
class Something
{
has Str:D $.my is rw is required;
method something(Str :$somearg! --> ID) { ... }
}
The type is used to represent arguments for GraphQL::Fields and Directives arguments as well as the inputFields of a GraphQL::InputObjectType. Has a $.type attribute and optionally a $.defaultValue attribute.
my $inputvalue = GraphQL::InputValue.new(name => 'somearg',
type => $GraphQLString,
defaultValue => 'some default');
in GSL:
somearg: String = "some default"
in Perl:
Str :$somearg = 'some default'
In addition to the inherited .name, .description, .isDeprecated, .deprecationReason, has attributes .args which is an array of GraphQL::InputValues, and .type which is the type of this field. Since the Field is the place where the Schema connects to resolvers, there is also a .resolver attribute which can be connected to arbitrary code. Much more about resolvers in Resolution below.
my $field = GraphQL::Field.new(
name => 'myfield',
type => $GraphQLString,
args => GraphQL::InputValue.new(
name => 'somearg',
type => $GraphQLString,
defaultValue => 'some default'),
resolver => sub { ... });
In GSL:
myfield(somearg: String = "some default"): String
In Perl:
method myfield(Str :$somearg = 'some default' --> Str) { ... }
Note that as a strongly, staticly typed system, every argument must be a named argument, and have an attached type (a valid one in the list above that map to GraphQL types), and the return must specify a type.
You can deprecate by setting the attributes .isDeprecated and optionally .deprecationReason or using the GSL @deprecate directive described below.
In addition to the inherited $.name, $.description, and @.fieldlist, also has the attribute @.possibleTypes with the list of object types that implement the interface. You needn't set @.possibleTypes, as each GraphQL::Object specifies which interfaces they implement, and the Schema finalization will list them all here.
my $interface = GraphQL::Interface.new(
name => 'myinterface',
fieldlist => (GraphQL::Field.new(...), GraphQL::Field.new(...))
);
In GSL:
interface myinterface {
...fields...
}
In addition to the inherited $.name, $.description, and @.fieldlist, also has the attribute @.interfaces with the interfaces which the object implements, and the .kind() method which always returns 'OBJECT'.
my $obj = GraphQL::Object.new(
name => 'myobject',
interfaces => ($someinterface, $someotherinterface),
fieldlist => (GraphQL::Field.new(...), GraphQL::Field.new(...))
);
In GSL:
type myobject implements someinterface, someotherinterface {
...fields...
}
In Perl:
class myobject {
...fields...
}
NOTE: Interfaces aren't yet implemented for the perl classes.
Input Objects are object like types used as inputs to queries. Their .kind() method returns 'INPUT_OBJECT'. They have a @.inputFields array of GraphQL::InputValues, very similar to the fields defined within a normal Object.
my $obj = GraphQL::InputObjectType.new(
name => 'myinputobject',
inputFields => (GraphQL::InputValue.new(...), GraphQL::InputValue.new(...)
);
In GSL:
input myinputobject {
...inputvalues...
}
In Perl, you must specify a class explicitly as a GraphQL::InputObject:
class myinputobject is GraphQL::InputObject {
...inputvalues...
}
A union has .kind() = 'UNION', and a @.possibleTypes attribute listing the types of the union.
my $union = GraphQL::Union.new(
name => 'myunion',
possibleTypes => ($someobject, $someotherobject)
);
In GSL:
union myunion = someobject | someotherobject
NOTE: Not yet implemented in Perl classes.
Has .kind() = 'ENUM', and @.enumValues with a list of GraphQL::EnumValues. The accessor method for .enumValues() takes an optional Bool argument :$includeDeprecated which will either include deprecated values or exclude them.
my $enum = GraphQL::Enum.new(
name => 'myenum',
enumValues => (GraphQL::EnumValue.new(...), GraphQL::EnumValue.new(...))
);
In GSL:
enum myenum { VAL1 VAL2 ... }
In Perl:
enum myenum <VAL1 VAL2 ...>;
Still needs work...