include::attributes.adoc[]




[[client]]
= Client

Spring for GraphQL includes client support for executing GraphQL requests over HTTP,
WebSocket, and RSocket.



[[client-graphqlclient]]
== `GraphQlClient`

`GraphQlClient` defines a common workflow for executing GraphQL requests and
subscriptions that is independent of and agnostic to the underlying transport. To create
an instance, you'll need to start from either the <<client-httpgraphqlclient,
HttpGraphQlClient>> or the <<client-websocketgraphqlclient,WebSocketGraphQlClient>>
extensions.

Each `GraphQlClient` extension provides a transport specific `Builder`. There is also a
shared, base <<client-graphqlclient-builder>> in `GraphQlClient` with common options for
all extensions.



[[client-httpgraphqlclient]]
=== HTTP

`HttpGraphQlClient` uses
{spring-framework-ref-docs}/web-reactive.html#webflux-client[WebClient] to execute
GraphQL requests over HTTP.

[source,java,indent=0,subs="verbatim,quotes"]
----
WebClient webClient = ... ;
HttpGraphQlClient graphQlClient = HttpGraphQlClient.create(webClient);
----

The `HttpGraphQlClient` extension is nothing but a `GraphQlClient` with a specialized
builder. Once created, it exposes the same workflow for request execution that is
independent of the underlying transport.

This means you can only configure HTTP request details at build time, and
those apply to all requests through that client instance. To change HTTP request
details, use `mutate()` on an existing `HttpGraphQlClient` to create another
instance with different configuration:

[source,java,indent=0,subs="verbatim,quotes"]
----
    WebClient webClient = ... ;

	HttpGraphQlClient graphQlClient = HttpGraphQlClient.builder(webClient)
			.headers(headers -> headers.setBasicAuth("joe", "..."))
			.build();

	// Perform requests with graphQlClient...

	HttpGraphQlClient anotherGraphQlClient = graphQlClient.mutate()
			.headers(headers -> headers.setBasicAuth("peter", "..."))
			.build();

	// Perform requests with anotherGraphQlClient...

----



[[client-websocketgraphqlclient]]
=== WebSocket

`WebSocketGraphQlClient` uses
{spring-framework-ref-docs}/web-reactive.html#webflux-websocket-client[WebSocketClient]
from Spring WebFlux to execute GraphQL requests over WebSocket:

[source,java,indent=0,subs="verbatim,quotes"]
----
	String url = "http://localhost:8080/graphql";
	WebSocketClient client = new ReactorNettyWebSocketClient();

	WebSocketGraphQlClient graphQlClient = WebSocketGraphQlClient.builder(url, client).build();
----

Once created, `WebSocketGraphQlClient` exposes the same transport agnostic workflow for
request execution as any `GrahQlClient`. To change any transport details, use `mutate()`
on an existing `WebSocketGraphQlClient` to create another with different configuration:

[source,java,indent=0,subs="verbatim,quotes"]
----
	URI url = ... ;
	WebSocketClient client = ... ;

	WebSocketGraphQlClient graphQlClient = WebSocketGraphQlClient.builder(url, client)
			.headers(headers -> headers.setBasicAuth("joe", "..."))
			.build();

	// Use graphQlClient...

	WebSocketGraphQlClient anotherGraphQlClient = graphQlClient.mutate()
			.headers(headers -> headers.setBasicAuth("peter", "..."))
			.build();

	// Use anotherGraphQlClient...

----



[[client-rsocketgraphqlclient]]
=== RSocket

`RSocketGraphQlClient` uses
{spring-framework-ref-docs}/web-reactive.html#rsocket-requester[RSocketRequester]
to execute GraphQL requests over RSocket requests.

[source,java,indent=0,subs="verbatim,quotes"]
----
	RSocketGraphQlClient graphQlClient =
			RSocketGraphQlClient.builder()
					.websocket(URI.create("http://localhost:8080/graphql"))
					.build();
----

Once created, `RSocketGraphQlClient` exposes the same transport agnostic workflow for
request execution as any `GrahQlClient`.



[[client-websocketgraphqlclient-connection]]
==== Connection

A connection is established transparently when requests are made. There is only one
shared, active connection at a time. If the connection is lost, it is re-established on
the next request.

`WebSocketGraphQlClient` also exposes lifecycle methods:

- `start()` - connect the WebSocket and initialize the GraphQL session. This can be used
on startup up to be ready for requests, but it is not required.
- `stop()` - cancels ongoing requests and subscriptions, and closes the connection. A
stopped client rejects new requests. Use `start()` to re-establish the connection and
allow requests again.



[[client-websocketgraphqlclient-interceptor]]
==== Interceptor

The https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md[GraphQL over WebSocket]
protocol defines a number of connection oriented messages in addition to executing
requests. For example, a client sends `"connection_init"` and the server responds with
`"connection_ack"` at the start of a connection.

For WebSocket transport specific interception, you can create a
`WebSocketGraphQlClientInterceptor`:

[source,java,indent=0,subs="verbatim,quotes"]
----
	static class MyInterceptor implements WebSocketGraphQlClientInterceptor {

		@Override
		public Mono<Object> connectionInitPayload() {
			// ... the "connection_init" payload to send
		}

		@Override
		public Mono<Void> handleConnectionAck(Map<String, Object> ackPayload) {
			// ... the "connection_ack" payload received
		}

	}
----

<<client-interception,Register>> the above interceptor as any other
`GraphQlClientInterceptor` and use it also to intercept GraphQL requests, but note there
can be at most one interceptor of type `WebSocketGraphQlClientInterceptor`.



[[client-graphqlclient-builder]]
=== Builder

`GraphQlClient` defines a parent `Builder` with common configuration options for the
builders of all extensions. Currently, it has lets you configure:

- `DocumentSource` strategy to load the document for a request from a file
- <<client-interception>> of executed requests




[[client-requests]]
== Requests

Once you have a <<client-graphqlclient>>, you can begin to perform requests via
<<client-requests-retrieve, retrieve()>> or <<client-requests-execute, execute()>>
where the former is only a shortcut for the latter.



[[client-requests-retrieve]]
=== Retrieve

The below retrieves and decodes the data for a query:

[source,java,indent=0,subs="verbatim,quotes"]
----
	String document = "{" +
			"  project(slug:\"spring-framework\") {" +
			"	name" +
			"	releases {" +
			"	  version" +
			"	}"+
			"  }" +
			"}";

	Mono<Project> projectMono = graphQlClient.document(document) <1>
			.retrieve("project") <2>
			.toEntity(Project.class); <3>
----
<1> The operation to perform.
<2> The path under the "data" key in the response map to decode from.
<3> Decode the data at the path to the target type.

The input document is a `String` that could be a literal or produced through a code
generated request object. You can also define documents in files and use a
<<client-requests-document-source>> to resole them by file name.

The path is relative to the "data" key and uses a simple dot (".") separated notation
for nested fields with optional array indices for list elements, e.g. `"project.name"`
or `"project.releases[0].version"`.

Decoding can result in `FieldAccessException` if the given path is not present, or the
field value is `null` and has an error. `FieldAccessException` provides access to the
response and the field:

[source,java,indent=0,subs="verbatim,quotes"]
----
	Mono<Project> projectMono = graphQlClient.document(document)
			.retrieve("project")
			.toEntity(Project.class)
			.onErrorResume(FieldAccessException.class, ex -> {
				ClientGraphQlResponse response = ex.getResponse();
				// ...
				ResponseField field = ex.getField();
				// ...
			});
----



[[client-requests-execute]]
=== Execute

<<client-requests-retrieve>> is only a shortcut to decode from a single path in the
response map. For more control, use the `execute` method and handle the response:

For example:

[source,java,indent=0,subs="verbatim,quotes"]
----

	Mono<Project> projectMono = graphQlClient.document(document)
			.execute()
			.map(response -> {
				if (!response.isValid()) {
					// Request failure... <1>
				}

				ResponseField field = response.field("project");
				if (!field.hasValue()) {
					if (field.getError() != null) {
						// Field failure... <2>
					}
					else {
						// Optional field set to null... <3>
					}
				}

				return field.toEntity(Project.class); <4>
			});
----
<1> The response does not have data, only errors
<2> Field that is `null` and has an associated error
<3> Field that was set to `null` by its `DataFetcher`
<4> Decode the data at the given path



[[client-requests-document-source]]
=== Document Source

The document for a request is a `String` that may be defined in a local variable or
constant, or it may be produced through a code generated request object.

You can also create document files with extensions `.graphql` or `.gql` under
`"graphql-documents/"` on the classpath and refer to them by file name.

For example, given a file called `projectReleases.graphql` in
`src/main/resources/graphql-documents`, with content:

[source,graphql,indent=0,subs="verbatim,quotes"]
.src/main/resources/graphql/project.graphql
----
	query projectReleases($slug: ID!) {
		project(slug: $slug) {
			name
			releases {
				version
			}
		}
	}
----

You can then:

[source,java,indent=0,subs="verbatim,quotes"]
----
	Mono<Project> projectMono = graphQlClient.documentName("projectReleases") <1>
			.variable("slug", "spring-framework") <2>
			.retrieve()
			.toEntity(Project.class);
----
<1> Load the document from "project.graphql"
<2> Provide variable values.

The "JS GraphQL" plugin for IntelliJ supports GraphQL query files with code completion.

You can use the `GraphQlClient` <<client-graphqlclient-builder>> to customize the
`DocumentSource` for loading documents by names.




[[client-subscriptions]]
== Subscription Requests

`GraphQlClient` can execute subscriptions over transports that support it. Currently, only
the WebSocket transport supports GraphQL streams, so you'll need to create a
<<client-websocketgraphqlclient,WebSocketGraphQlClient>>.



[[client-subscriptions-retrieve]]
=== Retrieve

To start a subscription stream, use `retrieveSubscription` which is similar to
<<client-requests-retrieve,retrieve>> for a single response but returning a stream of
responses, each decoded to some data:

[source,java,indent=0,subs="verbatim,quotes"]
----
	Flux<String> greetingFlux = client.document("subscription { greetings }")
			.retrieveSubscription("greeting")
			.toEntity(String.class);
----

A subscription stream may end with:

- `SubscriptionErrorException` if the server ends the
subscription with an explicit "error" message that contains one or more GraphQL errors.
The exception provides access to the GraphQL errors decoded from that message.
- `GraphQlTransportException` such as `WebSocketDisconnectedException` if the underlying
connection is closed or lost in which case you can use the `retry` operator to reestablish
the connection and start the subscription again.






[[client-subscriptions-execute]]
=== Execute

<<client-subscriptions-retrieve>> is only a shortcut to decode from a single path in each
response map. For more control, use the `executeSubscription` method and handle each
response directly:

[source,java,indent=0,subs="verbatim,quotes"]
----
	Flux<String> greetingFlux = client.document("subscription { greetings }")
			.executeSubscription()
			.map(response -> {
				if (!response.isValid()) {
					// Request failure...
				}

				ResponseField field = response.field("project");
				if (!field.hasValue()) {
					if (field.getError() != null) {
						// Field failure...
					}
					else {
						// Optional field set to null... <3>
					}
				}

				return field.toEntity(String.class)
			});
----




[[client-interception]]
== Interception

You create a `GraphQlClientInterceptor` to intercept all requests through a client:

[source,java,indent=0,subs="verbatim,quotes"]
----
static class MyInterceptor implements GraphQlClientInterceptor {

	@Override
	public Mono<ClientGraphQlResponse> intercept(ClientGraphQlRequest request, Chain chain) {
		// ...
		return chain.next(request);
	}

	@Override
	public Flux<ClientGraphQlResponse> interceptSubscription(ClientGraphQlRequest request, SubscriptionChain chain) {
		// ...
		return chain.next(request);
	}

}
----

Once the interceptor is created, register it through the client builder:

[source,java,indent=0,subs="verbatim,quotes"]
----
	URI url = ... ;
	WebSocketClient client = ... ;

	WebSocketGraphQlClient graphQlClient = WebSocketGraphQlClient.builder(url, client)
			.interceptor(new MyInterceptor())
			.build();
----

