From: Charles McGarvey <chazmcgarvey@brokenzipper.com>
Date: Mon, 16 Mar 2020 00:10:40 +0000 (-0600)
Subject: add README
X-Git-Tag: v0.601~4
X-Git-Url: https://git.brokenzipper.com/gitweb?a=commitdiff_plain;h=a1190420f86c2511c10c3ae0664d299447079a64;p=chaz%2Fgraphql-client

add README
---

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5f4df5b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,190 @@
+# NAME
+
+GraphQL::Client - A GraphQL client
+
+# VERSION
+
+version 0.600
+
+# SYNOPSIS
+
+    my $graphql = GraphQL::Client->new(url => 'http://localhost:4000/graphql');
+
+    # Example: Hello world!
+
+    my $response = $graphql->execute('{hello}');
+
+    # Example: Kitchen sink
+
+    my $query = q[
+        query GetHuman {
+            human(id: $human_id) {
+                name
+                height
+            }
+        }
+    ];
+    my $variables = {
+        human_id => 1000,
+    };
+    my $operation_name = 'GetHuman';
+    my $transport_options = {
+        headers => {
+            authorization => 'Bearer s3cr3t',
+        },
+    };
+    my $response = $graphql->execute($query, $variables, $operation_name, $transport_options);
+
+    # Example: Asynchronous with Mojo::UserAgent (promisify requires Future::Mojo)
+
+    my $ua = Mojo::UserAgent->new;
+    my $graphql = GraphQL::Client->new(ua => $ua, url => 'http://localhost:4000/graphql');
+
+    my $future = $graphql->execute('{hello}');
+
+    $future->promisify->then(sub {
+        my $response = shift;
+        ...
+    });
+
+# DESCRIPTION
+
+`GraphQL::Client` provides a simple way to execute [GraphQL](https://graphql.org/) queries and
+mutations on a server.
+
+This module is the programmatic interface. There is also a [graphql](#cli-program).
+
+GraphQL servers are usually served over HTTP. The provided transport, [GraphQL::Client::http](https://metacpan.org/pod/GraphQL%3A%3AClient%3A%3Ahttp), lets
+you plug in your own user agent, so this client works naturally with [HTTP::Tiny](https://metacpan.org/pod/HTTP%3A%3ATiny),
+[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.
+
+# ATTRIBUTES
+
+## url
+
+The URL of a GraphQL endpoint, e.g. `"http://myapiserver/graphql"`.
+
+## class
+
+The package name of a transport.
+
+By default this is automatically determined from the protocol portion of the ["url"](#url).
+
+## transport
+
+The transport object.
+
+By default this is automatically constructed based on the ["class"](#class).
+
+## unpack
+
+Whether or not to "unpack" the response, which enables a different style for error-handling.
+
+Default is 0.
+
+See ["ERROR HANDLING"](#error-handling).
+
+# METHODS
+
+## new
+
+    $graphql = GraphQL::Client->new(%attributes);
+
+Construct a new client.
+
+## execute
+
+    $response = $graphql->execute($query);
+    $response = $graphql->execute($query, \%variables);
+    $response = $graphql->execute($query, \%variables, $operation_name);
+    $response = $graphql->execute($query, \%variables, $operation_name, \%transport_options);
+    $response = $graphql->execute($query, \%variables, \%transport_options);
+
+Execute a request on a GraphQL server, and get a response.
+
+By default, the response will either be a hashref with the following structure or a [Future](https://metacpan.org/pod/Future) that
+resolves to such a hashref, depending on the transport and how it is configured.
+
+    {
+        data   => {
+            field1  => {...}, # or [...]
+            ...
+        },
+        errors => [
+            { message => 'some error message blah blah blah' },
+            ...
+        ],
+    }
+
+Note: Setting the ["unpack"](#unpack) attribute affects the response shape.
+
+# ERROR HANDLING
+
+There are two different styles for handling errors.
+
+If ["unpack"](#unpack) is 0 (off), every response -- whether success or failure -- is enveloped like this:
+
+    {
+        data   => {...},
+        errors => [...],
+    }
+
+where `data` might be missing or undef if errors occurred (though not necessarily) and `errors`
+will be missing if the response completed without error.
+
+It is up to you to check for errors in the response, so your code might look like this:
+
+    my $response = $graphql->execute(...);
+    if (my $errors = $response->{errors}) {
+        # handle $errors
+    }
+    else {
+        my $data = $response->{data};
+        # do something with $data
+    }
+
+If `unpack` is 1 (on), then ["execute"](#execute) will return just the data if there were no errors,
+otherwise it will throw an exception. So your code would instead look like this:
+
+    my $data = eval { $graphql->execute(...) };
+    if (my $error = $@) {
+        # handle errors
+    }
+    else {
+        # do something with $data
+    }
+
+Or if you want to handle errors in a different stack frame, your code is simply this:
+
+    my $data = $graphql->execute(...);
+    # do something with $data
+
+Both styles map to [Future](https://metacpan.org/pod/Future) responses intuitively. If `unpack` is 0, the response always resolves
+to the envelope structure. If `unpack` is 1, successful responses will resolve to just the data and
+errors will fail/reject.
+
+# SEE ALSO
+
+- [graphql](https://metacpan.org/pod/graphql) - CLI program
+- [GraphQL](https://metacpan.org/pod/GraphQL) - Perl implementation of a GraphQL server
+- [https://graphql.org/](https://graphql.org/) - GraphQL project website
+
+# BUGS
+
+Please report any bugs or feature requests on the bugtracker website
+[https://github.com/chazmcgarvey/graphql-client/issues](https://github.com/chazmcgarvey/graphql-client/issues)
+
+When submitting a bug or request, please include a test-file or a
+patch to an existing test-file that illustrates the bug or desired
+feature.
+
+# AUTHOR
+
+Charles McGarvey <chazmcgarvey@brokenzipper.com>
+
+# COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2020 by Charles McGarvey.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.