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 graphql.
57 GraphQL servers are usually served over HTTP. The provided transport,
58 GraphQL::Client::http, lets you plug in your own user agent, so this
59 client works naturally with HTTP::Tiny, Mojo::UserAgent, and more. You
60 can also use HTTP::AnyUA middleware.
66 The URL of a GraphQL endpoint, e.g. "http://myapiserver/graphql".
70 The package name of a transport.
72 By default this is automatically determined from the protocol portion
79 By default this is automatically constructed based on the "class".
83 Whether or not to "unpack" the response, which enables a different
84 style for error-handling.
94 $graphql = GraphQL::Client->new(%attributes);
96 Construct a new client.
100 $response = $graphql->execute($query);
101 $response = $graphql->execute($query, \%variables);
102 $response = $graphql->execute($query, \%variables, $operation_name);
103 $response = $graphql->execute($query, \%variables, $operation_name, \%transport_options);
104 $response = $graphql->execute($query, \%variables, \%transport_options);
106 Execute a request on a GraphQL server, and get a response.
108 By default, the response will either be a hashref with the following
109 structure or a Future that resolves to such a hashref, depending on the
110 transport and how it is configured.
114 field1 => {...}, # or [...]
118 { message => 'some error message blah blah blah' },
123 Note: Setting the "unpack" attribute affects the response shape.
127 There are two different styles for handling errors.
129 If "unpack" is 0 (off), every response -- whether success or failure --
130 is enveloped like this:
137 where data might be missing or undef if errors occurred (though not
138 necessarily) and errors will be missing if the response completed
141 It is up to you to check for errors in the response, so your code might
144 my $response = $graphql->execute(...);
145 if (my $errors = $response->{errors}) {
149 my $data = $response->{data};
150 # do something with $data
153 If unpack is 1 (on), then "execute" will return just the data if there
154 were no errors, otherwise it will throw an exception. So your code
155 would instead look like this:
157 my $data = eval { $graphql->execute(...) };
158 if (my $error = $@) {
162 # do something with $data
165 Or if you want to handle errors in a different stack frame, your code
168 my $data = $graphql->execute(...);
169 # do something with $data
171 Both styles map to Future responses intuitively. If unpack is 0, the
172 response always resolves to the envelope structure. If unpack is 1,
173 successful responses will resolve to just the data and errors will
178 * graphql - CLI program
180 * GraphQL - Perl implementation of a GraphQL server
182 * https://graphql.org/ - GraphQL project website
186 Please report any bugs or feature requests on the bugtracker website
187 https://github.com/chazmcgarvey/graphql-client/issues
189 When submitting a bug or request, please include a test-file or a patch
190 to an existing test-file that illustrates the bug or desired feature.
194 Charles McGarvey <chazmcgarvey@brokenzipper.com>
196 COPYRIGHT AND LICENSE
198 This software is copyright (c) 2020 by Charles McGarvey.
200 This is free software; you can redistribute it and/or modify it under
201 the same terms as the Perl 5 programming language system itself.