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

   1 NAME
   2
   3     GraphQL::Client - A GraphQL client
   4
   5 VERSION
   6
   7     version 0.601
   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 "CLI
  56     program".
  57
  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.
  62
  63 ATTRIBUTES
  64
  65  url
  66
  67     The URL of a GraphQL endpoint, e.g. "http://myapiserver/graphql".
  68
  69  unpack
  70
  71     Whether or not to "unpack" the response, which enables a different
  72     style for error-handling.
  73
  74     Default is 0.
  75
  76     See "ERROR HANDLING".
  77
  78  transport_class
  79
  80     The package name of a transport.
  81
  82     This is optional if the correct transport can be correctly determined
  83     from the "url".
  84
  85  transport
  86
  87     The transport object.
  88
  89     By default this is automatically constructed based on "transport_class"
  90     or "url".
  91
  92 METHODS
  93
  94  new
  95
  96         $graphql = GraphQL::Client->new(%attributes);
  97
  98     Construct a new client.
  99
 100  execute
 101
 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);
 107
 108     Execute a request on a GraphQL server, and get a response.
 109
 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.
 113
 114         {
 115             data   => {
 116                 field1  => {...}, # or [...]
 117                 ...
 118             },
 119             errors => [
 120                 { message => 'some error message blah blah blah' },
 121                 ...
 122             ],
 123         }
 124
 125     Note: Setting the "unpack" attribute affects the response shape.
 126
 127 ERROR HANDLING
 128
 129     There are two different styles for handling errors.
 130
 131     If "unpack" is 0 (off, the default), every response -- whether success
 132     or failure -- is enveloped like this:
 133
 134         {
 135             data   => {...},
 136             errors => [...],
 137         }
 138
 139     where data might be missing or undef if errors occurred (though not
 140     necessarily) and errors will be missing if the response completed
 141     without error.
 142
 143     It is up to you to check for errors in the response, so your code might
 144     look like this:
 145
 146         my $response = $graphql->execute(...);
 147         if (my $errors = $response->{errors}) {
 148             # handle $errors
 149         }
 150         else {
 151             my $data = $response->{data};
 152             # do something with $data
 153         }
 154
 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:
 158
 159         my $data = eval { $graphql->execute(...) };
 160         if (my $error = $@) {
 161             my $resp = $error->{response};
 162             # handle errors
 163         }
 164         else {
 165             # do something with $data
 166         }
 167
 168     Or if you want to handle errors in a different stack frame, your code
 169     is simply this:
 170
 171         my $data = $graphql->execute(...);
 172         # do something with $data
 173
 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
 177     fail/reject.
 178
 179 SEE ALSO
 180
 181       * graphql - CLI program
 182
 183       * GraphQL - Perl implementation of a GraphQL server
 184
 185       * https://graphql.org/ - GraphQL project website
 186
 187 BUGS
 188
 189     Please report any bugs or feature requests on the bugtracker website
 190     https://github.com/chazmcgarvey/graphql-client/issues
 191
 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.
 194
 195 AUTHOR
 196
 197     Charles McGarvey <chazmcgarvey@brokenzipper.com>
 198
 199 COPYRIGHT AND LICENSE
 200
 201     This software is copyright (c) 2020 by Charles McGarvey.
 202
 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.
 205