File Coverage

blib/lib/GraphQL.pm
Criterion Covered Total %
statement 8 8 100.0
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 11 11 100.0


line stmt bran cond sub pod time code
1             package GraphQL;
2              
3 1     1   102728 use 5.014;
  1         3  
4 1     1   6 use strict;
  1         4  
  1         30  
5 1     1   6 use warnings;
  1         3  
  1         74  
6              
7             =head1 NAME
8              
9             GraphQL - Perl implementation of GraphQL
10              
11             =cut
12              
13             our $VERSION = '0.52';
14              
15             =begin markdown
16              
17             # PROJECT STATUS
18              
19             | OS | Build status |
20             |:-------:|--------------:|
21             | Linux | [![Build Status](https://travis-ci.org/graphql-perl/graphql-perl.svg?branch=master)](https://travis-ci.org/graphql-perl/graphql-perl) |
22              
23             [![CPAN version](https://badge.fury.io/pl/GraphQL.svg)](https://metacpan.org/pod/GraphQL) [![Coverage Status](https://coveralls.io/repos/github/graphql-perl/graphql-perl/badge.svg?branch=master)](https://coveralls.io/github/graphql-perl/graphql-perl?branch=master)
24              
25             =end markdown
26              
27             =head1 SYNOPSIS
28              
29             use GraphQL::Schema;
30             use GraphQL::Type::Object;
31             use GraphQL::Type::Scalar qw($String);
32             use GraphQL::Execution qw(execute);
33              
34             my $schema = GraphQL::Schema->from_doc(<<'EOF');
35             type Query {
36             helloWorld: String
37             }
38             EOF
39             post '/graphql' => sub {
40             send_as JSON => execute(
41             $schema,
42             body_parameters->{query},
43             { helloWorld => 'Hello world!' },
44             undef,
45             body_parameters->{variables},
46             body_parameters->{operationName},
47             undef,
48             );
49             };
50              
51             The above is from L<the sample Dancer 2 applet|https://github.com/graphql-perl/sample-dancer2>.
52              
53             =head1 DESCRIPTION
54              
55             This module is a port of the GraphQL reference implementation,
56             L<graphql-js|https://github.com/graphql-js/graphql-js>, to Perl 5.
57              
58             It now supports Promises, allowing asynchronous operation. See
59             L<Mojolicious::Plugin::GraphQL> for an example of how to take advantage
60             of this.
61              
62             As of 0.39, supports GraphQL subscriptions.
63              
64             See L<GraphQL::Type> for description of how to create GraphQL types.
65              
66             =head2 Introduction to GraphQL
67              
68             GraphQL is a technology that lets clients talk to APIs via a single
69             endpoint, which acts as a single "source of the truth". This means clients
70             do not need to seek the whole picture from several APIs. Additionally,
71             it makes this efficient in network traffic, time, and programming effort:
72              
73             =over
74              
75             =item Network traffic
76              
77             The request asks for exactly what it wants, which it gets, and no
78             more. No wasted traffic.
79              
80             =item Time
81              
82             It gets all the things it needs in one go, including any connected
83             resources, so it does not need to make several requests to fill its
84             information requirement.
85              
86             =item Programming effort
87              
88             With "fragments" that can be attached to user-interface components,
89             keeping track of what information a whole page needs to request can be
90             automated. See L<Relay|https://facebook.github.io/relay/> or
91             L<Apollo|http://dev.apollodata.com/> for more on this.
92              
93             =back
94              
95             =head2 Basic concepts
96              
97             GraphQL implements a system featuring a L<schema|GraphQL::Schema>,
98             which features various classes of L<types|GraphQL::Type>, some of which
99             are L<objects|GraphQL::Type::Object>. Special objects provide the roots
100             of queries (mandatory), and mutations and subscriptions (both optional).
101              
102             Objects have fields, each of which can be specified to take arguments,
103             and which have a return type. These are effectively the properties and/or
104             methods on the type. If they return an object, then a query can specify
105             subfields of that object, and so on - as alluded to in the "time-saving"
106             point above.
107              
108             For more, see the JavaScript tutorial in L</"SEE ALSO">.
109              
110             =head2 Hooking your system up to GraphQL
111              
112             You will need to decide how to model your system in GraphQL terms. This
113             will involve deciding on what L<output object types|GraphQL::Type::Object>
114             you have, what fields they have, and what arguments and return-types
115             those fields have.
116              
117             Additionally, you will need to design mutations if you want to be able
118             to update/create/delete data. This requires some thought for return types,
119             to ensure you can get all the information you need to proceed to avoid
120             extra round-trips.
121              
122             The easiest way to achieve these things is to make a
123             L<GraphQL::Plugin::Convert> subclass, to encapsulate the specifics of
124             your system. See the documentation for further information.
125              
126             Finally, you should consider whether you need "subscriptions". These
127             are designed to hook into WebSockets. Apollo has a L<JavaScript
128             module|https://github.com/apollographql/graphql-subscriptions> for this.
129              
130             Specifying types and fields is straightforward. See L<the
131             document|GraphQL::Type::Library/FieldMapOutput> for how to make resolvers.
132              
133             =head1 DEBUGGING
134              
135             To debug, set environment variable C<GRAPHQL_DEBUG> to a true value.
136              
137             =head1 EXPORT
138              
139             None yet.
140              
141             =head1 SEE ALSO
142              
143             L<SQL::Translator::Producer::GraphQL> - produce GraphQL schemas from a L<DBIx::Class::Schema> (or in fact any SQL database)
144              
145             L<GraphQL::Plugin::Convert::DBIC> - produce working GraphQL schema from
146             a L<DBIx::Class::Schema>
147              
148             L<GraphQL::Plugin::Convert::OpenAPI> - produce working GraphQL schema
149             from an OpenAPI specification
150              
151             L<Sample Mojolicious OpenAPI to GraphQL applet|https://github.com/graphql-perl/sample-mojolicious-openapi>
152              
153             L<Sample Dancer 2 applet|https://github.com/graphql-perl/sample-dancer2>
154              
155             L<Sample Mojolicious applet|https://github.com/graphql-perl/sample-mojolicious>
156              
157             L<Dancer2::Plugin::GraphQL>
158              
159             L<Mojolicious::Plugin::GraphQL>
160              
161             L<http://facebook.github.io/graphql/> - GraphQL specification
162              
163             L<http://graphql.org/graphql-js/> - Tutorial on the JavaScript version,
164             highly recommended.
165             L<Translation to
166             graphql-perl|http://blogs.perl.org/users/ed_j/2017/10/graphql-perl---graphql-js-tutorial-translation-to-graphql-perl-and-mojoliciousplugingraphql.html>.
167              
168             =head1 AUTHOR
169              
170             Ed J, C<< <etj at cpan.org> >>
171              
172             =head1 BUGS
173              
174             Please report any bugs or feature requests on
175             L<https://github.com/graphql-perl/graphql-perl/issues>.
176              
177             Or, if you prefer email and/or RT: to C<bug-graphql
178             at rt.cpan.org>, or through the web interface at
179             L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=GraphQL>. I will be
180             notified, and then you'll automatically be notified of progress on your
181             bug as I make changes.
182              
183             =head1 ACKNOWLEDGEMENTS
184              
185             The creation of this work has been sponsored by Perl Careers:
186             L<https://perl.careers/>.
187              
188             Artur Khabibullin C<< <rtkh at cpan.org> >> contributed valuable ports
189             of the JavaScript tests.
190              
191             The creation of the subscriptions functionality in this work has been
192             sponsored by Sanctus.app: L<https://sanctus.app>.
193              
194             =head1 LICENSE AND COPYRIGHT
195              
196             Copyright 2017 Ed J.
197              
198             This program is free software; you can redistribute it and/or modify it
199             under the terms of the the Artistic License (2.0). You may obtain a
200             copy of the full license at:
201              
202             L<http://www.perlfoundation.org/artistic_license_2_0>
203              
204             =cut
205              
206             1;