Dogcows Code - chaz/graphql-client/blob - README

   1 NAME
   2
   3     GraphQL::Client - A GraphQL client
   4
   5 VERSION
   6
   7     version 0.600
   8
   9 SYNOPSIS
  10
  11         my $graphql = GraphQL::Client->new(url => 'http://localhost:4000/graphql');
  12
  13         # Example: Hello world!
  14
  15         my $response = $graphql->execute('{hello}');
  16
  17         # Example: Kitchen sink
  18
  19         my $query = q[
  20             query GetHuman {
  21                 human(id: $human_id) {
  22                     name
  23                     height
  24                 }
  25             }
  26         ];
  27         my $variables = {
  28             human_id => 1000,
  29         };
  30         my $operation_name = 'GetHuman';
  31         my $transport_options = {
  32             headers => {
  33                 authorization => 'Bearer s3cr3t',
  34             },
  35         };
  36         my $response = $graphql->execute($query, $variables, $operation_name, $transport_options);
  37
  38         # Example: Asynchronous with Mojo::UserAgent (promisify requires Future::Mojo)
  39
  40         my $ua = Mojo::UserAgent->new;
  41         my $graphql = GraphQL::Client->new(ua => $ua, url => 'http://localhost:4000/graphql');
  42
  43         my $future = $graphql->execute('{hello}');
  44
  45         $future->promisify->then(sub {
  46             my $response = shift;
  47             ...
  48         });
  49
  50 DESCRIPTION
  51
  52     GraphQL::Client provides a simple way to execute GraphQL
  53     <https://graphql.org/> queries and mutations on a server.
  54
  55     This module is the programmatic interface. There is also a graphql.
  56
  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.
  61
  62 ATTRIBUTES
  63
  64  url
  65
  66     The URL of a GraphQL endpoint, e.g. "http://myapiserver/graphql".
  67
  68  class
  69
  70     The package name of a transport.
  71
  72     By default this is automatically determined from the protocol portion
  73     of the "url".
  74
  75  transport
  76
  77     The transport object.
  78
  79     By default this is automatically constructed based on the "class".
  80
  81  unpack
  82
  83     Whether or not to "unpack" the response, which enables a different
  84     style for error-handling.
  85
  86     Default is 0.
  87
  88     See "ERROR HANDLING".
  89
  90 METHODS
  91
  92  new
  93
  94         $graphql = GraphQL::Client->new(%attributes);
  95
  96     Construct a new client.
  97
  98  execute
  99
 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);
 105
 106     Execute a request on a GraphQL server, and get a response.
 107
 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.
 111
 112         {
 113             data   => {
 114                 field1  => {...}, # or [...]
 115                 ...
 116             },
 117             errors => [
 118                 { message => 'some error message blah blah blah' },
 119                 ...
 120             ],
 121         }
 122
 123     Note: Setting the "unpack" attribute affects the response shape.
 124
 125 ERROR HANDLING
 126
 127     There are two different styles for handling errors.
 128
 129     If "unpack" is 0 (off), every response -- whether success or failure --
 130     is enveloped like this:
 131
 132         {
 133             data   => {...},
 134             errors => [...],
 135         }
 136
 137     where data might be missing or undef if errors occurred (though not
 138     necessarily) and errors will be missing if the response completed
 139     without error.
 140
 141     It is up to you to check for errors in the response, so your code might
 142     look like this:
 143
 144         my $response = $graphql->execute(...);
 145         if (my $errors = $response->{errors}) {
 146             # handle $errors
 147         }
 148         else {
 149             my $data = $response->{data};
 150             # do something with $data
 151         }
 152
 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:
 156
 157         my $data = eval { $graphql->execute(...) };
 158         if (my $error = $@) {
 159             # handle errors
 160         }
 161         else {
 162             # do something with $data
 163         }
 164
 165     Or if you want to handle errors in a different stack frame, your code
 166     is simply this:
 167
 168         my $data = $graphql->execute(...);
 169         # do something with $data
 170
 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
 174     fail/reject.
 175
 176 SEE ALSO
 177
 178       * graphql - CLI program
 179
 180       * GraphQL - Perl implementation of a GraphQL server
 181
 182       * https://graphql.org/ - GraphQL project website
 183
 184 BUGS
 185
 186     Please report any bugs or feature requests on the bugtracker website
 187     https://github.com/chazmcgarvey/graphql-client/issues
 188
 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.
 191
 192 AUTHOR
 193
 194     Charles McGarvey <chazmcgarvey@brokenzipper.com>
 195
 196 COPYRIGHT AND LICENSE
 197
 198     This software is copyright (c) 2020 by Charles McGarvey.
 199
 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.
 202