.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "GraphQL 3pm" .TH GraphQL 3pm "2022-03-27" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" GraphQL \- Perl implementation of GraphQL .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& use GraphQL::Schema; \& use GraphQL::Type::Object; \& use GraphQL::Type::Scalar qw($String); \& use GraphQL::Execution qw(execute); \& \& my $schema = GraphQL::Schema\->from_doc(<<\*(AqEOF\*(Aq); \& type Query { \& helloWorld: String \& } \& EOF \& post \*(Aq/graphql\*(Aq => sub { \& send_as JSON => execute( \& $schema, \& body_parameters\->{query}, \& { helloWorld => \*(AqHello world!\*(Aq }, \& undef, \& body_parameters\->{variables}, \& body_parameters\->{operationName}, \& undef, \& ); \& }; .Ve .PP The above is from the sample Dancer 2 applet . .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module is a port of the GraphQL reference implementation, graphql-js , to Perl 5. .PP It now supports Promises, allowing asynchronous operation. See Mojolicious::Plugin::GraphQL for an example of how to take advantage of this. .PP As of 0.39, supports GraphQL subscriptions. .PP See GraphQL::Type for description of how to create GraphQL types. .SS "Introduction to GraphQL" .IX Subsection "Introduction to GraphQL" GraphQL is a technology that lets clients talk to APIs via a single endpoint, which acts as a single \*(L"source of the truth\*(R". This means clients do not need to seek the whole picture from several APIs. Additionally, it makes this efficient in network traffic, time, and programming effort: .IP "Network traffic" 4 .IX Item "Network traffic" The request asks for exactly what it wants, which it gets, and no more. No wasted traffic. .IP "Time" 4 .IX Item "Time" It gets all the things it needs in one go, including any connected resources, so it does not need to make several requests to fill its information requirement. .IP "Programming effort" 4 .IX Item "Programming effort" With \*(L"fragments\*(R" that can be attached to user-interface components, keeping track of what information a whole page needs to request can be automated. See Relay or Apollo for more on this. .SS "Basic concepts" .IX Subsection "Basic concepts" GraphQL implements a system featuring a schema, which features various classes of types, some of which are objects. Special objects provide the roots of queries (mandatory), and mutations and subscriptions (both optional). .PP Objects have fields, each of which can be specified to take arguments, and which have a return type. These are effectively the properties and/or methods on the type. If they return an object, then a query can specify subfields of that object, and so on \- as alluded to in the \*(L"time-saving\*(R" point above. .PP For more, see the JavaScript tutorial in \*(L"\s-1SEE ALSO\*(R"\s0. .SS "Hooking your system up to GraphQL" .IX Subsection "Hooking your system up to GraphQL" You will need to decide how to model your system in GraphQL terms. This will involve deciding on what output object types you have, what fields they have, and what arguments and return-types those fields have. .PP Additionally, you will need to design mutations if you want to be able to update/create/delete data. This requires some thought for return types, to ensure you can get all the information you need to proceed to avoid extra round-trips. .PP The easiest way to achieve these things is to make a GraphQL::Plugin::Convert subclass, to encapsulate the specifics of your system. See the documentation for further information. .PP Finally, you should consider whether you need \*(L"subscriptions\*(R". These are designed to hook into WebSockets. Apollo has a JavaScript module for this. .PP Specifying types and fields is straightforward. See the document for how to make resolvers. .SH "DEBUGGING" .IX Header "DEBUGGING" To debug, set environment variable \f(CW\*(C`GRAPHQL_DEBUG\*(C'\fR to a true value. .SH "EXPORT" .IX Header "EXPORT" None yet. .SH "SEE ALSO" .IX Header "SEE ALSO" SQL::Translator::Producer::GraphQL \- produce GraphQL schemas from a DBIx::Class::Schema (or in fact any \s-1SQL\s0 database) .PP GraphQL::Plugin::Convert::DBIC \- produce working GraphQL schema from a DBIx::Class::Schema .PP GraphQL::Plugin::Convert::OpenAPI \- produce working GraphQL schema from an OpenAPI specification .PP Sample Mojolicious OpenAPI to GraphQL applet .PP Sample Dancer 2 applet .PP Sample Mojolicious applet .PP Dancer2::Plugin::GraphQL .PP Mojolicious::Plugin::GraphQL .PP \- GraphQL specification .PP \- Tutorial on the JavaScript version, highly recommended. Translation to graphql-perl . .SH "AUTHOR" .IX Header "AUTHOR" Ed J, \f(CW\*(C`\*(C'\fR .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests on . .PP Or, if you prefer email and/or \s-1RT:\s0 to \f(CW\*(C`bug\-graphql at rt.cpan.org\*(C'\fR, or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" The creation of this work has been sponsored by Perl Careers: . .PP Artur Khabibullin \f(CW\*(C`\*(C'\fR contributed valuable ports of the JavaScript tests. .PP The creation of the subscriptions functionality in this work has been sponsored by Sanctus.app: . .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright 2017 Ed J. .PP This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at: .PP