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

   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](https://graphql.org/) queries and
  53 mutations on a server.
  54
  55 This module is the programmatic interface. There is also a ["CLI program"](https://metacpan.org/pod/graphql).
  56
  57 GraphQL servers are usually served over HTTP. The provided transport, [GraphQL::Client::http](https://metacpan.org/pod/GraphQL%3A%3AClient%3A%3Ahttp), lets
  58 you plug in your own user agent, so this client works naturally with [HTTP::Tiny](https://metacpan.org/pod/HTTP%3A%3ATiny),
  59 [Mojo::UserAgent](https://metacpan.org/pod/Mojo%3A%3AUserAgent), and more. You can also use [HTTP::AnyUA](https://metacpan.org/pod/HTTP%3A%3AAnyUA) middleware.
  60
  61 # ATTRIBUTES
  62
  63 ## url
  64
  65 The URL of a GraphQL endpoint, e.g. `"http://myapiserver/graphql"`.
  66
  67 ## unpack
  68
  69 Whether or not to "unpack" the response, which enables a different style for error-handling.
  70
  71 Default is 0.
  72
  73 See ["ERROR HANDLING"](#error-handling).
  74
  75 ## transport\_class
  76
  77 The package name of a transport.
  78
  79 This is optional if the correct transport can be correctly determined from the ["url"](#url).
  80
  81 ## transport
  82
  83 The transport object.
  84
  85 By default this is automatically constructed based on ["transport\_class"](#transport_class) or ["url"](#url).
  86
  87 # METHODS
  88
  89 ## new
  90
  91     $graphql = GraphQL::Client->new(%attributes);
  92
  93 Construct a new client.
  94
  95 ## execute
  96
  97     $response = $graphql->execute($query);
  98     $response = $graphql->execute($query, \%variables);
  99     $response = $graphql->execute($query, \%variables, $operation_name);
 100     $response = $graphql->execute($query, \%variables, $operation_name, \%transport_options);
 101     $response = $graphql->execute($query, \%variables, \%transport_options);
 102
 103 Execute a request on a GraphQL server, and get a response.
 104
 105 By default, the response will either be a hashref with the following structure or a [Future](https://metacpan.org/pod/Future) that
 106 resolves to such a hashref, depending on the transport and how it is configured.
 107
 108     {
 109         data   => {
 110             field1  => {...}, # or [...]
 111             ...
 112         },
 113         errors => [
 114             { message => 'some error message blah blah blah' },
 115             ...
 116         ],
 117     }
 118
 119 Note: Setting the ["unpack"](#unpack) attribute affects the response shape.
 120
 121 # ERROR HANDLING
 122
 123 There are two different styles for handling errors.
 124
 125 If ["unpack"](#unpack) is 0 (off, the default), every response -- whether success or failure -- is enveloped
 126 like this:
 127
 128     {
 129         data   => {...},
 130         errors => [...],
 131     }
 132
 133 where `data` might be missing or undef if errors occurred (though not necessarily) and `errors`
 134 will be missing if the response completed without error.
 135
 136 It is up to you to check for errors in the response, so your code might look like this:
 137
 138     my $response = $graphql->execute(...);
 139     if (my $errors = $response->{errors}) {
 140         # handle $errors
 141     }
 142     else {
 143         my $data = $response->{data};
 144         # do something with $data
 145     }
 146
 147 If `unpack` is 1 (on), then ["execute"](#execute) will return just the data if there were no errors,
 148 otherwise it will throw an exception. So your code would instead look like this:
 149
 150     my $data = eval { $graphql->execute(...) };
 151     if (my $error = $@) {
 152         my $resp = $error->{response};
 153         # handle errors
 154     }
 155     else {
 156         # do something with $data
 157     }
 158
 159 Or if you want to handle errors in a different stack frame, your code is simply this:
 160
 161     my $data = $graphql->execute(...);
 162     # do something with $data
 163
 164 Both styles map to [Future](https://metacpan.org/pod/Future) responses intuitively. If `unpack` is 0, the response always resolves
 165 to the envelope structure. If `unpack` is 1, successful responses will resolve to just the data and
 166 errors will fail/reject.
 167
 168 # SEE ALSO
 169
 170 - [graphql](https://metacpan.org/pod/graphql) - CLI program
 171 - [GraphQL](https://metacpan.org/pod/GraphQL) - Perl implementation of a GraphQL server
 172 - [https://graphql.org/](https://graphql.org/) - GraphQL project website
 173
 174 # BUGS
 175
 176 Please report any bugs or feature requests on the bugtracker website
 177 [https://github.com/chazmcgarvey/graphql-client/issues](https://github.com/chazmcgarvey/graphql-client/issues)
 178
 179 When submitting a bug or request, please include a test-file or a
 180 patch to an existing test-file that illustrates the bug or desired
 181 feature.
 182
 183 # AUTHOR
 184
 185 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 186
 187 # COPYRIGHT AND LICENSE
 188
 189 This software is copyright (c) 2020 by Charles McGarvey.
 190
 191 This is free software; you can redistribute it and/or modify it under
 192 the same terms as the Perl 5 programming language system itself.