= Vert.x Web GraphQL

Vert.x Web GraphQL extends Vert.x Web with the https://www.graphql-java.com[GraphQL-Java] library so that you can build a GraphQL server.

TIP: This is the reference documentation for Vert.x Web GraphQL.
It is highly recommended to get familiar with the GraphQL-Java API first.
You may start by reading the https://www.graphql-java.com/documentation/getting-started/[GraphQL-Java documentation].

== Getting started

To use this module, add the following to the _dependencies_ section of your Maven POM file:

[source,xml,subs="+attributes"]
----
<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-web-graphql</artifactId>
  <version>${maven.version}</version>
</dependency>
----

Or, if you use Gradle:

[source,groovy,subs="+attributes"]
----
compile 'io.vertx:vertx-web-graphql:${maven.version}'
----

== Handlers setup

=== HTTP

Create a Vert.x Web {@link io.vertx.ext.web.Route} and a {@link io.vertx.ext.web.handler.graphql.GraphQLHandler} for it:

[source,$lang]
----
{@link examples.GraphQLExamples#handlerSetup}
----

[TIP]
====
The `GraphQLHandler` supports https://www.apollographql.com/docs/apollo-server/performance/apq/[Apollo's _automatic persisted queries_], provided GraphQL-Java is configured accordingly:

[source,$lang]
----
{@link examples.GraphQLExamples#persistedQueries}
----
====

The handler serves both `GET` and `POST` requests.
However, you can restrict the service to one type of HTTP method:

[source,$lang]
----
{@link examples.GraphQLExamples#handlerSetupPost}
----

IMPORTANT: The {@link io.vertx.ext.web.handler.graphql.GraphQLHandler} requires a {@link io.vertx.ext.web.handler.BodyHandler} to read `POST` requests content.

==== Query batching

Query batching consists in posting an array instead of a single object to the GraphQL endpoint.

Vert.x Web GraphQL can handle such requests but by default the feature is disabled.
To enable it, create the {@link io.vertx.ext.web.handler.graphql.GraphQLHandler} with options:

[source,$lang]
----
{@link examples.GraphQLExamples#handlerSetupBatching}
----

=== GraphQL over WebSocket

Vert.x Web GraphQL is compatible with the https://github.com/enisdenjo/graphql-ws[GraphQL over Websocket protocol].

The websocket transport is specially useful when you need to add subscriptions to your GraphQL schema, but you can also use it for queries and mutations.

CAUTION: By default, the configuration does not include a default `Origin` property.
To prevent Cross-Site WebSocket Hijacking attacks from web browsers, it is recommended to set this property to the internet facing origin of the application.
This will enforce a check that web sockets origin is from this application.
This check is important because WebSockets are not restrained by the same-origin policy, an attacker can easily initiate a WebSocket request from a malicious webpage targeting the `ws://` or `wss://` endpoint URL of the GraphQL WS handler.

[source,$lang]
----
{@link examples.GraphQLExamples#addGraphQLWSHandlerToRouter}
----

[IMPORTANT]
====
The client will ask for the `graphql-transport-ws` websocket subprotocol.
Consequently, it has to be added to the list of supported subprotocols in the server configuration:

[source,$lang]
----
{@link examples.GraphQLExamples#configureServerForGraphQLWS}
----
====

[TIP]
====
The `GraphQLWSHandler` supports https://www.apollographql.com/docs/apollo-server/performance/apq/[Apollo's _automatic persisted queries_], provided GraphQL-Java is configured accordingly:

[source,$lang]
----
{@link examples.GraphQLExamples#persistedQueries}
----
====

To support both HTTP and Websockets on the same URI, the {@link io.vertx.ext.web.handler.graphql.ws.GraphQLWSHandler} must be installed to the {@link io.vertx.ext.web.Router} before the {@link io.vertx.ext.web.handler.graphql.GraphQLHandler}:

[source,$lang]
----
{@link examples.GraphQLExamples#configureGraphQLWSAndHttpOnSamePath}
----

IMPORTANT: A _subscription_ `DataFetcher` has to return a `org.reactivestreams.Publisher` instance.

=== GraphiQL IDE

As you are building your application, testing your GraphQL queries in https://github.com/graphql/graphiql[GraphiQL] can be handy.

To do so, create a route for GraphiQL resources and a {@link io.vertx.ext.web.handler.graphql.GraphiQLHandler} for them:

[source,$lang]
----
{@link examples.GraphQLExamples#handlerSetupGraphiQL}
----

Then browse to http://localhost:8080/graphiql/.

NOTE: The GraphiQL user interface is disabled by default for security reasons.
This is why you must configure the {@link io.vertx.ext.web.handler.graphql.GraphiQLHandlerOptions} to enable it.

[TIP]
====
GraphiQL is enabled automatically when Vert.x Web runs in development mode.
To switch the development mode on, use the `VERTXWEB_ENVIRONMENT` environment variable or `vertxweb.environment` system property and set it to `dev`.
In this case, create the {@link io.vertx.ext.web.handler.graphql.GraphiQLHandler} without changing the `enabled` property.
====

If your application is protected by authentication, you can customize the headers sent by GraphiQL dynamically:

[source,$lang]
----
{@link examples.GraphQLExamples#handlerSetupGraphiQLAuthn}
----

Please refer to the {@link io.vertx.ext.web.handler.graphql.GraphiQLHandlerOptions} documentation for further details.

== Fetching data

The GraphQL-Java API is very well suited for the asynchronous world: the asynchronous execution strategy is the default for queries (serial asynchronous for mutations).

To https://vertx.io/docs/vertx-core/java/#golden_rule[avoid blocking the event loop], all you have to do is implement https://www.graphql-java.com/documentation/data-fetching/[data fetchers] that return a `CompletionStage` instead of the result directly.

[source,$lang]
----
{@link examples.GraphQLExamples#completionStageDataFetcher}
----

[TIP]
====
Instead of converting Vert.x {@link io.vertx.core.Future} to `java.util.concurrent.CompletionStage` manually in every data fetcher implementation, configure GraphQL-Java with the {@link io.vertx.ext.web.handler.graphql.instrumentation.VertxFutureAdapter} https://www.graphql-java.com/documentation/instrumentation/[instrumentation].

First, declare the instrumentation while configuring GraphQL-Java.

[source,$lang]
----
{@link examples.GraphQLExamples#vertxFutureAdapter}
----

Then you can return Vert.x futures directly.

[source,$lang]
----
{@link examples.GraphQLExamples#futureDataFetcher}
----
====

=== Providing data fetchers with some context

Very often, the {@link io.vertx.ext.web.handler.graphql.GraphQLHandler}, or the {@link io.vertx.ext.web.handler.graphql.ws.GraphQLWSHandler}, will be declared after other route handlers.
For example, you could protect your application with authentication.

In this case, it is likely that your data fetchers will need to know which user is logged-in, to narrow down the results.

For this, you may retrieve the {@link io.vertx.ext.web.RoutingContext} object by inspecting the `DataFetchingEnvironment`:

[source,$lang]
----
{@link examples.GraphQLExamples#routingContextInDataFetchingEnvironment}
----

=== JSON data results

The default GraphQL data fetcher is the `PropertyDataFetcher`.
It is able to read the fields of your domain objects without further configuration.

Nevertheless, in Vert.x applications it is common to work with {@link io.vertx.core.json.JsonArray} and {@link io.vertx.core.json.JsonObject}.
The `PropertyDataFetcher` can read the items in a `JsonArray` out of the box, but not the fields of a `JsonObject`.

The solution to this problem depends on your GraphQL-Java version.

NOTE: Both solutions let you mix `JsonObject`, `JsonArray` and domain objects results.

==== GraphQL-Java 20 and later

Configure GraphQL-Java with the {@link io.vertx.ext.web.handler.graphql.instrumentation.JsonObjectAdapter} https://www.graphql-java.com/documentation/instrumentation/[instrumentation].

[source,$lang]
----
{@link examples.GraphQLExamples#jsonObjectAdapter}
----

==== GraphQL-Java 19 and before

Configure GraphQL-Java to use {@link io.vertx.ext.web.handler.graphql.schema.VertxPropertyDataFetcher} instead:

[source,$lang]
----
{@link examples.GraphQLExamples#jsonData}
----

=== Batch loading

Dataloaders help you to load data efficiently by batching fetch requests and caching results.

First, create a batch loader:

[source,$lang]
----
{@link examples.GraphQLExamples#createBatchLoader}
----

Then, configure the {@link io.vertx.ext.web.handler.graphql.GraphQLHandler} to create a `DataLoaderRegistry` for each request:

[source,$lang]
----
{@link examples.GraphQLExamples#dataLoaderRegistry}
----

=== File uploads

https://github.com/jaydenseric/graphql-multipart-request-spec[GraphQL multipart request] is an interoperable multipart form field structure for `GraphQL` requests.
By enabling this functionality, GraphQL clients will be able to upload files using a single mutation call.
All the server-side file handling will be abstracted by the {@link io.vertx.ext.web.handler.graphql.GraphQLHandler}.

To enable it, create a {@link io.vertx.ext.web.handler.graphql.GraphQLHandler} with the requestMultipartEnabled configuration set to true and add the {@link io.vertx.ext.web.handler.BodyHandler} to the router.

[source,$lang]
----
{@link examples.GraphQLExamples#setupGraphQLHandlerMultipart}
----

IMPORTANT: If the router does not have a {@link io.vertx.ext.web.handler.BodyHandler}, the multipart request parser will not be able to handle the GraphQL mutation call.

Finally, create the `Upload` scalar and set it to the `RuntimeWiring`:

[source,$lang]
----
{@link examples.GraphQLExamples#setRuntimeScalar}
----

The `FileUpload` instance can be accessed using the `DataFetchingEnvironment::getArgument` method.

[source,$lang]
----
{@link examples.GraphQLExamples#getFileUpload}
----

ifeval::["$lang" == "java"]
include::override/rxjava3.adoc[]
endif::[]
