3 GraphQL::Client - A GraphQL client
11 my $graphql = GraphQL::Client->new(url => 'http://localhost:4000/graphql');
13 # Example: Hello world!
15 my $response = $graphql->execute('{hello}');
17 # Example: Kitchen sink
21 human(id: $human_id) {
30 my $operation_name = 'GetHuman';
31 my $transport_options = {
33 authorization => 'Bearer s3cr3t',
36 my $response = $graphql->execute($query, $variables, $operation_name, $transport_options);
38 # Example: Asynchronous with Mojo::UserAgent (promisify requires Future::Mojo)
40 my $ua = Mojo::UserAgent->new;
41 my $graphql = GraphQL::Client->new(ua => $ua, url => 'http://localhost:4000/graphql');
43 my $future = $graphql->execute('{hello}');
45 $future->promisify->then(sub {
52 GraphQL::Client provides a simple way to execute GraphQL
53 <https://graphql.org/> queries and mutations on a server.
55 This module is the programmatic interface. There is also a "CLI
58 GraphQL servers are usually served over HTTP. The provided transport,
59 GraphQL::Client::http, lets you plug in your own user agent, so this
60 client works naturally with HTTP::Tiny, Mojo::UserAgent, and more. You
61 can also use HTTP::AnyUA middleware.
67 The URL of a GraphQL endpoint, e.g. "http://myapiserver/graphql".
71 Whether or not to "unpack" the response, which enables a different
72 style for error-handling.
80 The package name of a transport.
82 This is optional if the correct transport can be correctly determined
89 By default this is automatically constructed based on "transport_class"
96 $graphql = GraphQL::Client->new(%attributes);
98 Construct a new client.
102 $response = $graphql->execute($query);
103 $response = $graphql->execute($query, \%variables);
104 $response = $graphql->execute($query, \%variables, $operation_name);
105 $response = $graphql->execute($query, \%variables, $operation_name, \%transport_options);
106 $response = $graphql->execute($query, \%variables, \%transport_options);
108 Execute a request on a GraphQL server, and get a response.
110 By default, the response will either be a hashref with the following
111 structure or a Future that resolves to such a hashref, depending on the
112 transport and how it is configured.
116 field1 => {...}, # or [...]
120 { message => 'some error message blah blah blah' },
125 Note: Setting the "unpack" attribute affects the response shape.
129 There are two different styles for handling errors.
131 If "unpack" is 0 (off, the default), every response -- whether success
132 or failure -- is enveloped like this:
139 where data might be missing or undef if errors occurred (though not
140 necessarily) and errors will be missing if the response completed
143 It is up to you to check for errors in the response, so your code might
146 my $response = $graphql->execute(...);
147 if (my $errors = $response->{errors}) {
151 my $data = $response->{data};
152 # do something with $data
155 If unpack is 1 (on), then "execute" will return just the data if there
156 were no errors, otherwise it will throw an exception. So your code
157 would instead look like this:
159 my $data = eval { $graphql->execute(...) };
160 if (my $error = $@) {
161 my $resp = $error->{response};
165 # do something with $data
168 Or if you want to handle errors in a different stack frame, your code
171 my $data = $graphql->execute(...);
172 # do something with $data
174 Both styles map to Future responses intuitively. If unpack is 0, the
175 response always resolves to the envelope structure. If unpack is 1,
176 successful responses will resolve to just the data and errors will
181 * graphql - CLI program
183 * GraphQL - Perl implementation of a GraphQL server
185 * https://graphql.org/ - GraphQL project website
189 Please report any bugs or feature requests on the bugtracker website
190 https://github.com/chazmcgarvey/graphql-client/issues
192 When submitting a bug or request, please include a test-file or a patch
193 to an existing test-file that illustrates the bug or desired feature.
197 Charles McGarvey <chazmcgarvey@brokenzipper.com>
199 COPYRIGHT AND LICENSE
201 This software is copyright (c) 2020 by Charles McGarvey.
203 This is free software; you can redistribute it and/or modify it under
204 the same terms as the Perl 5 programming language system itself.