Improvements to the GraphQL-Java integration

Vert.x 4.4 ships sev­eral im­prove­ments to the GraphQL-​Java in­te­gra­tion with Vert.x Web.

In this ar­ti­cle, we’ll go through the most im­por­tant of them:

• GraphiQL IDE up­grade (slick UI and sub­scrip­tions sup­port),
• sim­pli­fied data fetcher de­f­i­n­i­tions (using in­stru­men­ta­tion),
• sup­port of Apollo’s Au­to­matic Per­sisted Queries (APQ).

GraphiQL IDE upgrade

Vert.x Web GraphQL now ships the lat­est ver­sion of the GraphQL IDE. Com­pared to the old ver­sion, you’ll get a slick user in­ter­face, ed­itable code his­tory and the abil­ity to switch be­tween light and dark modes.

More im­por­tantly, our in­te­gra­tion lever­ages the GraphiQL toolkit fetcher. This means you can test sub­scrip­tions over the GraphQLWS pro­to­col.

Simplified data fetcher definitions

Data fetchers returning Vert.x Future

In pre­vi­ous ver­sions, you could cre­ate asyn­chro­nous data fetch­ers with VertxDataFetcher:

VertxDataFetcher<List<Link>> dataFetcher = VertxDataFetcher.create((env, promise) -> {
  retrieveLinksFromBackend(env, promise);
});

RuntimeWiring runtimeWiring = RuntimeWiring.newRuntimeWiring()
  .type("Query", builder -> builder.dataFetcher("allLinks", dataFetcher))
  .build();

This method re­quired to wrap every data fetcher de­f­i­n­i­tion man­u­ally. Be­sides, it was easy to for­get to do it, be­cause any ob­ject is a valid data fetcher re­sult. Con­se­quently, the com­piler wouldn’t com­plain.

Using GraphQL-​Java in­stru­men­ta­tion, in 4.4 it is pos­si­ble to wrap data fetch­ers au­to­mat­i­cally.

First, de­clare the in­stru­men­ta­tion while con­fig­ur­ing GraphQL-​Java.

graphQLBuilder.instrumentation(VertxFutureAdapter.create());

Then you can re­turn Vert.x fu­tures di­rectly.

DataFetcher<Future<List<Link>>> dataFetcher = environment -> {
  Future<List<Link>> future = retrieveLinksFromBackend(environment);
  return future;
};

Note that sim­i­lar func­tion­nal­ity is pro­vided for data fetch­ers re­turn­ing Rx­Java3’s Single or Maybe. Learn more about this in the work­ing with Vert.x Rx­i­fied APIs sec­tion of the doc­u­men­ta­tion.

JSON data results

The de­fault GraphQL-​Java data fetcher is the PropertyDataFetcher. It is able to read the fields of your do­main ob­jects with­out fur­ther con­fig­u­ra­tion.

Nev­er­the­less, in Vert.x ap­pli­ca­tions it is com­mon to work with JsonArray and JsonObject. The PropertyDataFetcher can read the items in a JsonAr­ray out of the box, but not the fields of a JsonObject…

If your project de­pends on GraphQL-​Java 20 (the de­fault in Vert.x 4.4), con­fig­ure GraphQL-​Java with the JsonObjectAdapter in­stru­men­ta­tion.

graphQLBuilder.instrumentation(new JsonObjectAdapter());

Support of Apollo’s Automatic Persisted Queries (APQ)

Apollo’s Au­to­matic Per­sisted Queries (APQ) im­prove net­work per­for­mance for large query strings.

Re­cent ver­sions of GraphQL-​Java pro­vide sup­port for ex­e­cu­tion of such queries. In Vert.x 4.4, the trans­port lay­ers (HTTP, GraphQLWS) are also ready to re­ceive them.

This re­quires to con­fig­ure GraphQL-​Java with a spe­cific preparsed doc­u­ment Provider:

graphQLBuilder.preparsedDocumentProvider(new ApolloPersistedQuerySupport(inMemoryPersistedQueryCache));

GraphQL-​Java comes with a sim­ple InMemoryPersistedQueryCache, but you could pro­vide your own (using, for ex­am­ple, the Caf­feine high per­for­mance caching li­brary).