Vert.x Web GraphQL extends Vert.x Web with the 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 GraphQL-Java documentation. |
Warning
|
This module has Tech Preview status, this means the API can change between versions. |
To use this module, add the following to the dependencies section of your Maven POM file:
<dependency>
<groupId>io.vertx</groupId>
<artifactId>vertx-web-graphql</artifactId>
<version>3.8.4</version>
</dependency>
Or, if you use Gradle:
compile 'io.vertx:vertx-web-graphql:3.8.4'
Create a Vert.x Web Route
and a GraphQLHandler
for it:
def graphQL = this.setupGraphQLJava()
router.route("/graphql").handler(GraphQLHandler.create(graphQL))
The handler serves both GET
and POST
requests.
However you can restrict the service to one type of HTTP method:
def graphQL = this.setupGraphQLJava()
router.post("/graphql").handler(GraphQLHandler.create(graphQL))
Tip
|
The GraphQLHandler does not require a BodyHandler to read POST requests content.
|
As you are building your application, testing your GraphQL queries in GraphiQL can be handy.
To do so, create a route for GraphiQL resources and a GraphiQLHandler
for them:
def options = [
enabled:true
]
router.route("/graphiql/*").handler(GraphiQLHandler.create(options))
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 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 GraphiQLHandler without changing the enabled property.
|
If your application is protected by authentication, you can customize the headers sent by GraphiQL dynamically:
graphiQLHandler.graphiQLRequestHeaders({ rc ->
def token = rc.get("token")
return MultiMap.caseInsensitiveMultiMap().add(io.vertx.core.http.HttpHeaders.AUTHORIZATION, "Bearer ${token}")
})
router.route("/graphiql/*").handler(graphiQLHandler)
Please refer to the GraphiQLHandlerOptions
documentation for further details.
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 GraphQLHandler
with options:
def options = [
requestBatchingEnabled:true
]
def handler = GraphQLHandler.create(graphQL, options)
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 avoid blocking the event loop, all you have to do is implement data fetchers that return a CompletionStage
instead of the result directly.
def dataFetcher = { environment ->
def completableFuture = new java.util.concurrent.CompletableFuture()
this.retrieveLinksFromBackend(environment, { ar ->
if (ar.succeeded()) {
completableFuture.complete(ar.result())
} else {
completableFuture.completeExceptionally(ar.cause())
}
})
return completableFuture
}
def runtimeWiring = graphql.schema.idl.RuntimeWiring.newRuntimeWiring().type("Query", { builder ->
builder.dataFetcher("allLinks", dataFetcher)
}).build()
Implementing a data fetcher that returns a CompletionStage
is not a complex task.
But when you work with Vert.x callback-based APIs, it requires a bit of boilerplate.
This is where the VertxDataFetcher
can help:
def dataFetcher = new io.vertx.ext.web.handler.graphql.VertxDataFetcher({ environment, future ->
this.retrieveLinksFromBackend(environment, future)
})
def runtimeWiring = graphql.schema.idl.RuntimeWiring.newRuntimeWiring().type("Query", { builder ->
builder.dataFetcher("allLinks", dataFetcher)
}).build()
Very often, the GraphQLHandler
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.
Let’s say your authentication layer stores a User
object in the RoutingContext
.
You may retrieve this object by inspecting the DataFetchingEnvironment
:
def dataFetcher = new io.vertx.ext.web.handler.graphql.VertxDataFetcher({ environment, future ->
def routingContext = environment.getContext()
def user = routingContext.get("user")
this.retrieveLinksPostedBy(user, future)
})
Note
|
The routing context is available with any kind of data fetchers, not just VertxDataFetcher .
|
If you prefer not to expose the routing context to your data fetchers, configure the GraphQL handler to customize the context object:
def dataFetcher = new io.vertx.ext.web.handler.graphql.VertxDataFetcher({ environment, future ->
// User as custom context object
def user = environment.getContext()
this.retrieveLinksPostedBy(user, future)
})
def graphQL = this.setupGraphQLJava(dataFetcher)
// Customize the query context object when setting up the handler
def handler = GraphQLHandler.create(graphQL).queryContext({ routingContext ->
return routingContext.get("user")
})
router.route("/graphql").handler(handler)
The default GraphQL data fetcher is PropertyDataFetcher
.
As a consequence, it will be able to read the fields of your domain objects without further configuration.
Nevertheless, some Vert.x data clients return JsonArray
and JsonObject
results.
If you don’t need (or don’t wish to) use a domain object layer, you can configure GraphQL-Java to use VertxPropertyDataFetcher
instead:
def builder = graphql.schema.idl.RuntimeWiring.newRuntimeWiring()
builder.wiringFactory(new graphql.schema.idl.WiringFactory())
Tip
|
VertxPropertyDataFetcher wraps a PropertyDataFetcher so you can still use it with domain objects.
|
Dataloaders help you to load data efficiently by batching fetch requests and caching results.
First, create a batch loader:
def linksBatchLoader = { keys, environment ->
return this.retrieveLinksFromBackend(keys, environment)
}
Tip
|
If you work with Vert.x callback-based APIs, you may use a VertxBatchLoader to simplify your code.
|
Then, configure the GraphQLHandler
to create a DataLoaderRegistry
for each request:
Code not translatable
You can use an Apollo WebSocketLink which connects over a websocket. This is specially useful if you want to add subscriptions to your GraphQL schema, but you can also use the websocket for queries and mutations.
def graphQL = this.setupGraphQLJava()
router.route("/graphql").handler(ApolloWSHandler.create(graphQL))
Important
|
To support the graphql-ws websocket subprotocol, it has to be added to the server configuration:
|
def httpServerOptions = [
websocketSubProtocols:"graphql-ws"
]
vertx.createHttpServer(httpServerOptions).requestHandler(router).listen(8080)
Note
|
If you want to support a WebSocketLink and a HttpLink in the same path, you can add the ApolloWSHandler in first place and then the GraphQLHandler. |
def graphQL = this.setupGraphQLJava()
router.route("/graphql").handler(ApolloWSHandler.create(graphQL))
router.route("/graphql").handler(GraphQLHandler.create(graphQL))
Here you can find how to configure the Apollo SubscriptionClient: https://github.com/apollographql/subscriptions-transport-ws
Important
|
A subscription DataFetcher has to return a org.reactivestreams.Publisher instance.
|