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

   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](https://graphql.org/) queries and
  53 mutations on a server.
  54
  55 This module is the programmatic interface. There is also a [graphql](#cli-program).
  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 ## class
  68
  69 The package name of a transport.
  70
  71 By default this is automatically determined from the protocol portion of the ["url"](#url).
  72
  73 ## transport
  74
  75 The transport object.
  76
  77 By default this is automatically constructed based on the ["class"](#class).
  78
  79 ## unpack
  80
  81 Whether or not to "unpack" the response, which enables a different style for error-handling.
  82
  83 Default is 0.
  84
  85 See ["ERROR HANDLING"](#error-handling).
  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), every response -- whether success or failure -- is enveloped like this:
 126
 127     {
 128         data   => {...},
 129         errors => [...],
 130     }
 131
 132 where `data` might be missing or undef if errors occurred (though not necessarily) and `errors`
 133 will be missing if the response completed without error.
 134
 135 It is up to you to check for errors in the response, so your code might look like this:
 136
 137     my $response = $graphql->execute(...);
 138     if (my $errors = $response->{errors}) {
 139         # handle $errors
 140     }
 141     else {
 142         my $data = $response->{data};
 143         # do something with $data
 144     }
 145
 146 If `unpack` is 1 (on), then ["execute"](#execute) will return just the data if there were no errors,
 147 otherwise it will throw an exception. So your code would instead look like this:
 148
 149     my $data = eval { $graphql->execute(...) };
 150     if (my $error = $@) {
 151         # handle errors
 152     }
 153     else {
 154         # do something with $data
 155     }
 156
 157 Or if you want to handle errors in a different stack frame, your code is simply this:
 158
 159     my $data = $graphql->execute(...);
 160     # do something with $data
 161
 162 Both styles map to [Future](https://metacpan.org/pod/Future) responses intuitively. If `unpack` is 0, the response always resolves
 163 to the envelope structure. If `unpack` is 1, successful responses will resolve to just the data and
 164 errors will fail/reject.
 165
 166 # SEE ALSO
 167
 168 - [graphql](https://metacpan.org/pod/graphql) - CLI program
 169 - [GraphQL](https://metacpan.org/pod/GraphQL) - Perl implementation of a GraphQL server
 170 - [https://graphql.org/](https://graphql.org/) - GraphQL project website
 171
 172 # BUGS
 173
 174 Please report any bugs or feature requests on the bugtracker website
 175 [https://github.com/chazmcgarvey/graphql-client/issues](https://github.com/chazmcgarvey/graphql-client/issues)
 176
 177 When submitting a bug or request, please include a test-file or a
 178 patch to an existing test-file that illustrates the bug or desired
 179 feature.
 180
 181 # AUTHOR
 182
 183 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 184
 185 # COPYRIGHT AND LICENSE
 186
 187 This software is copyright (c) 2020 by Charles McGarvey.
 188
 189 This is free software; you can redistribute it and/or modify it under
 190 the same terms as the Perl 5 programming language system itself.