GraphQL(3pm)

💖 GraphQL 💖

okay bestie, sit down, hydrate, because we're about to talk about the GraphQL(3pm) manual page and it is lowkey a whole vibe. This is the Perl implementation of GraphQL, and she is serving. ✨

---

✨ NAME ✨

GraphQL — a Perl implementation of GraphQL. that's it, that's the name, and it's iconic for it 💅

---

🦋 SYNOPSIS 🦋

here's the whole thing, copy-paste ready, no notes:

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,
  );
};

and pookie, that snippet above is straight from the sample Dancer 2 applet over at https://github.com/graphql-perl/sample-dancer2. go look at it, it's cute.

---

🌸 DESCRIPTION 🌸

so. this module is a port of the GraphQL reference implementation, graphql-js (that's https://github.com/graphql-js/graphql-js bestie, go click it), translated over to Perl 5. it's giving "I took the assignment and made it Perl". 🫶

It now supports Promises, which means asynchronous operation is on the menu. Want to see how to actually use that? Peep Mojolicious::Plugin::GraphQL for an example of how to take advantage of it. 👑

As of 0.39, it supports GraphQL subscriptions. yes, subscriptions. we've been upgraded.

And if you wanna know how to build GraphQL types? That's GraphQL::Type's whole job — go read that page for the description.

🌈 Introduction to GraphQL 🌈

GraphQL is a technology that lets clients talk to APIs via a single endpoint, which acts as a single "source of the truth". Translation: clients don't have to go begging to five different APIs to piece together the whole picture. and it makes all of this efficient — in network traffic, in time, and in programming effort:

• Network traffic — the request asks for exactly what it wants, which it gets, and no more. No wasted traffic. zero. not a single stray byte. 🎀
• 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. one trip, all the info, main character energy. ⭐
• Programming effort — with "fragments" that can be attached to user-interface components, keeping track of what information a whole page needs to request can be automated. See Relay (https://facebook.github.io/relay/) or Apollo (http://dev.apollodata.com/) for more on this. automation?? we love her. 🦋

💜 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).

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 "time-saving" point above. it's fields all the way down, bestie, and honestly? obsessed. 💅

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. This will involve deciding on what output object types you have, what fields they have, and what arguments and return-types those fields have.

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, so you can avoid extra round-trips. plan your return types, don't be messy. 🙈

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.

Finally, you should consider whether you need "subscriptions". These are designed to hook into WebSockets. Apollo has a JavaScript module for this: https://github.com/apollographql/graphql-subscriptions.

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

---

🔥 DEBUGGING 🔥

wanna debug? set the environment variable GRAPHQL_DEBUG to a true value. that's it. that's the whole section. go forth and ✨observe✨.

---

🍓 EXPORT 🍓

None yet. 😭 (we're waiting, bestie. patiently.)

---

👑 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 from a DBIx::Class::Schema
• GraphQL::Plugin::Convert::OpenAPI — produce working GraphQL schema from an OpenAPI specification
• Sample Mojolicious OpenAPI to GraphQL applet: https://github.com/graphql-perl/sample-mojolicious-openapi
• Sample Dancer 2 applet: https://github.com/graphql-perl/sample-dancer2
• Sample Mojolicious applet: https://github.com/graphql-perl/sample-mojolicious
• 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 to graphql-perl: http://blogs.perl.org/users/ed_j/2017/10/graphql-perl---graphql-js-tutorial-translation-to-graphql-perl-and-mojoliciousplugingraphql.html

---

💖 AUTHOR 💖

Ed J, "<etj at cpan.org>". thank you Ed, you ate. 👑

---

🎀 BUGS 🎀

Please report any bugs or feature requests on https://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 at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=GraphQL. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. communication!! we love a feedback loop. 🫶

---

🌟 ACKNOWLEDGEMENTS 🌟

The creation of this work has been sponsored by Perl Careers: https://perl.careers/. slay, sponsors, we appreciate you.

Artur Khabibullin "<rtkh at cpan.org>" contributed valuable ports of the JavaScript tests. a legend, honestly. 💜

The creation of the subscriptions functionality in this work has been sponsored by Sanctus.app: https://sanctus.app/. subscriptions said "thank you for funding me". ✨

---

🌈 LICENSE AND COPYRIGHT 🌈

Copyright 2017 Ed J.

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:

http://www.perlfoundation.org/artistic_license_2_0

heads up bestie: yes, the original really does say "the terms of the the Artistic License" — two "the"s, canon, we don't touch it. 💅

---

and that's the whole page, fr fr. this version of the manual page ships with perl v5.34.0, dated 2022-03-27, and it lives under the manual name GraphQL(3pm). no cap. bye bestie, go write some resolvers 🦋✨💖