1 package GraphQL
::Client
::http
;
2 # ABSTRACT: GraphQL over HTTP
8 use HTTP
::AnyUA
::Util
qw(www_form_urlencode);
12 our $VERSION = '999.999'; # VERSION
14 sub _croak
{ require Carp
; goto &Carp
::croak
}
18 my $self = @_ % 2 == 0 ? {@_} : $_[0];
24 my ($request, $options) = @_;
26 my $url = delete $options->{url
} || $self->url;
27 my $method = delete $options->{method} || $self->method;
29 $request && ref($request) eq 'HASH' or _croak
q{Usage: $http->execute(\%request)};
30 $request->{query
} or _croak
q{Request must have a query};
31 $url or _croak
q{URL must be provided};
33 my $data = {%$request};
35 if ($method eq 'GET' || $method eq 'HEAD') {
36 $data->{variables
} = $self->json->encode($data->{variables
}) if $data->{variables
};
37 my $params = www_form_urlencode
($data);
38 my $sep = $url =~ /^[^#]+\?/ ? '&' : '?';
39 $url =~ s/#/${sep}${params}#/ or $url .= "${sep}${params}";
42 my $encoded_data = $self->json->encode($data);
43 $options->{content
} = $encoded_data;
44 $options->{headers
}{'content-length'} = length $encoded_data;
45 $options->{headers
}{'content-type'} = 'application/json';
48 return $self->_handle_response($self->any_ua->request($method, $url, $options));
51 sub _handle_response
{
55 if (eval { $resp->isa('Future') }) {
56 return $resp->followed_by(sub {
59 if (my ($exception, $category, @other) = $f->failure) {
60 if (ref $exception eq 'HASH') {
61 my $resp = $exception;
62 return Future-
>done($self->_handle_error($resp));
69 exception_details
=> [$category, @other],
75 return Future-
>done($self->_handle_success($resp));
79 return $self->_handle_error($resp) if !$resp->{success
};
80 return $self->_handle_success($resp);
88 my $data = eval { $self->json->decode($resp->{content
}) };
89 my $content = $resp->{content
} // 'No content';
90 my $reason = $resp->{reason
} // '';
91 my $message = "HTTP transport returned $resp->{status} ($reason): $content";
99 http_response
=> $resp,
104 sub _handle_success
{
108 my $data = eval { $self->json->decode($resp->{content
}) };
109 if (my $exception = $@) {
111 error
=> "HTTP transport failed to decode response: $exception",
114 http_response
=> $resp,
122 http_response
=> $resp,
132 agent
=> $ENV{GRAPHQL_CLIENT_HTTP_USER_AGENT
} // "perl-graphql-client/$VERSION",
139 $self->{any_ua
} //= HTTP
::AnyUA-
>new(ua
=> $self->ua);
149 $self->{method} // 'POST';
154 $self->{json
} //= do {
155 require JSON
::MaybeXS
;
156 JSON
::MaybeXS-
>new(utf8
=> 1);
165 my $transport = GraphQL::Client::http->new(
166 url => 'http://localhost:5000/graphql',
171 query => 'query Greet($name: String) { hello(name: $name) }',
172 operationName => 'Greet',
173 variables => { name => 'Bob' },
177 authorization => 'Bearer s3cr3t',
180 my $response = $transport->execute($request, $options);
184 You probably shouldn't use this directly. Instead use L<GraphQL::Client>.
186 C<GraphQL::Client::http> is a GraphQL transport for HTTP. GraphQL is not required to be transported
187 via HTTP, but this is definitely the most common way.
189 This also serves as a reference implementation for C<GraphQL::Client> transports.
193 $transport = GraphQL::Client::http->new(%attributes);
195 Construct a new GraphQL HTTP transport.
201 $response = $client->execute(\%request);
202 $response = $client->execute(\%request, \%options);
204 Get a response from the GraphQL server.
206 The C<%request> structure must have a C<query> key whose value is the query or mutation string. It
207 may optionally have a C<variables> hashref and an C<operationName> string.
209 The C<%options> structure is optional and may contain options passed through to the user agent. The
210 only useful options are C<headers> (which should have a hashref value) and C<method> and C<url> to
211 override the attributes of the same names.
213 The response will either be a hashref with the following structure or a L<Future> that resolves to
217 response => { # decoded response (may be undef if an error occurred)
221 error => 'Something happened', # omitted if no error occurred
222 details => { # optional information which may aide troubleshooting
228 A user agent, such as:
231 * instance of a L<HTTP::Tiny> (this is the default if no user agent is provided)
232 * instance of a L<Mojo::UserAgent>
233 * the string C<"AnyEvent::HTTP">
236 See L<HTTP::AnyUA/"SUPPORTED USER AGENTS">.
240 The L<HTTP::AnyUA> instance. Can be used to apply middleware if desired.
244 The http URL of a GraphQL endpoint, e.g. C<"http://myapiserver/graphql">.
248 The HTTP method to use when querying the GraphQL server. Can be one of:
254 GraphQL servers should be able to handle both, but you can set this explicitly to one or the other
255 if you're dealing with a server that is opinionated. You can also provide a different HTTP method,
256 but anything other than C<GET> and C<POST> are less likely to work.
260 The L<JSON::XS> (or compatible) object used for encoding and decoding data structures to and from
263 Defaults to a L<JSON::MaybeXS>.
267 L<https://graphql.org/learn/serving-over-http/>