NAME

GraphQL - Perl implementation of GraphQL

PROJECT STATUS

SYNOPSIS

use GraphQL::Schema;
use GraphQL::Type::Object;
use GraphQL::Type::Scalar qw($String);
use GraphQL::Execution qw(execute);

my $schema = GraphQL::Schema->from_doc(<<'EOF');
type Query {
  helloWorld: String
}
EOF
post '/graphql' => sub {
  send_as JSON => execute(
    $schema,
    body_parameters->{query},
    { helloWorld => 'Hello world!' },
    undef,
    body_parameters->{variables},
    body_parameters->{operationName},
    undef,
  );
};

The above is from the sample Dancer 2 applet.

DESCRIPTION

This module is a port of the GraphQL reference implementation,graphql-js, to Perl 5.

It now supports Promises, allowing asynchronous operation. SeeMojolicious::Plugin::GraphQL for an example of how to take advantageof this.

As of 0.39, supports GraphQL subscriptions.

See GraphQL::Type for description of how to create GraphQL types.

Introduction to GraphQL

GraphQL is a technology that lets clients talk to APIs via a singleendpoint, which acts as a single "source of the truth". This means clientsdo not need to seek the whole picture from several APIs. Additionally,it makes this efficient in network traffic, time, and programming effort:

• Network traffic

  The request asks for exactly what it wants, which it gets, and nomore. No wasted traffic.

• Time

  It gets all the things it needs in one go, including any connectedresources, so it does not need to make several requests to fill itsinformation requirement.

• Programming effort

  With "fragments" that can be attached to user-interface components,keeping track of what information a whole page needs to request can beautomated. See Relay orApollo for more on this.

Basic concepts

GraphQL implements a system featuring a schema,which features various classes of types, some of whichare objects. Special objects provide the rootsof queries (mandatory), and mutations and subscriptions (both optional).

Objects have fields, each of which can be specified to take arguments,and which have a return type. These are effectively the properties and/ormethods on the type. If they return an object, then a query can specifysubfields of that object, and so on - as alluded to in the "time-saving"point above.

For more, see the JavaScript tutorial in "SEE ALSO".

Hooking your system up to GraphQL

You will need to decide how to model your system in GraphQL terms. Thiswill involve deciding on what output object typesyou have, what fields they have, and what arguments and return-typesthose fields have.

Additionally, you will need to design mutations if you want to be ableto update/create/delete data. This requires some thought for return types,to ensure you can get all the information you need to proceed to avoidextra round-trips.

The easiest way to achieve these things is to make aGraphQL::Plugin::Convert subclass, to encapsulate the specifics ofyour system. See the documentation for further information.

Finally, you should consider whether you need "subscriptions". Theseare designed to hook into WebSockets. Apollo has a JavaScriptmodule for this.

Specifying types and fields is straightforward. See thedocument for how to make resolvers.

DEBUGGING

To debug, set environment variable GRAPHQL_DEBUG to a true value.

EXPORT

None yet.

SEE ALSO

SQL::Translator::Producer::GraphQL - produce GraphQL schemas from a DBIx::Class::Schema (or in fact any SQL database)

GraphQL::Plugin::Convert::DBIC - produce working GraphQL schema froma DBIx::Class::Schema

GraphQL::Plugin::Convert::OpenAPI - produce working GraphQL schemafrom an OpenAPI specification

Sample Mojolicious OpenAPI to GraphQL applet

Sample Dancer 2 applet

Sample Mojolicious applet

Dancer2::Plugin::GraphQL

Mojolicious::Plugin::GraphQL

http://facebook.github.io/graphql/ - GraphQL specification

http://graphql.org/graphql-js/ - Tutorial on the JavaScript version,highly recommended.Translation tographql-perl.

AUTHOR

Ed J, <etj at cpan.org>

BUGS

Please report any bugs or feature requests onhttps://github.com/graphql-perl/graphql-perl/issues.

Or, if you prefer email and/or RT: to bug-graphql at rt.cpan.org, or through the web interface athttp://rt.cpan.org/NoAuth/ReportBug.html?Queue=GraphQL. I will benotified, and then you'll automatically be notified of progress on yourbug as I make changes.

ACKNOWLEDGEMENTS

The creation of this work has been sponsored by Perl Careers:https://perl.careers/.

Artur Khabibullin <rtkh at cpan.org> contributed valuable portsof the JavaScript tests.

The creation of the subscriptions functionality in this work has beensponsored by Sanctus.app: https://sanctus.app.

LICENSE AND COPYRIGHT

Copyright 2017 Ed J.

This program is free software; you can redistribute it and/or modify itunder the terms of the the Artistic License (2.0). You may obtain acopy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0