Quicker, easier GraphQL queries with Open Liberty 20.0.0.9

Open Liberty 20.0.0.9 lets developers experiment with the type-safe SmallRye GraphQL Client API, and write and run GraphQL queries and mutations more easily with a built-in GraphiQL user interface (UI). This article introduces the new features and updates in Open Liberty 20.0.0.9:

• Experiment with a third-party GraphQL client API.
• Use the built-in GraphiQL UI for faster queries and mutations.
• Give us your feedback!

Run your apps using Open Liberty 20.0.0.9

If you are using Maven, use these coordinates to update to the newest version of Open Liberty:

<dependency>
    <groupId>io.openliberty</groupId>
    <artifactId>openliberty-runtime</artifactId>
    <version>20.0.0.9</version>
    <type>zip</type>
</dependency>

For Gradle, enter:

dependencies {
    libertyRuntime group: 'io.openliberty', name: 'openliberty-runtime', version: '[20.0.0.9,)'
}

If you're using Docker, it's:

FROM open-liberty

Experiment with a third-party GraphQL client API

MicroProfile GraphQL has only been available in Open Liberty for a few months, and it is already a hit. That said, there are a few ways that we want to improve it and make it more complete. One feature that we want to improve is the GraphQL client API. While the official client API is not expected until the next release of MicroProfile GraphQL, you can start experimenting now with the type-safe SmallRye GraphQL client API.

SmallRye is the underlying implementation of MicroProfile GraphQL. You can access its above-and-beyond-the-spec features by adding the "third-party" API type visibility to your application:

<application name="MyGraphQLApp" location="MyGraphQLApp.war">
    <classloader apiTypeVisibility="+third-party"/>
</application>

This update lets you access SmallRye GraphQL APIs like the type-safe client. Note that these APIs might change in future releases because SmallRye is continuously evolving. For more information, please visit SmallRye GraphQL project. For Open Liberty 20.0.0.9, we are using SmallRye GraphQL 1.0.7.

Type-safe invocation for remote methods

The SmallRye GraphQL client APIs are very similar to MicroProfile Rest Client, which uses an interface to invoke remote methods in a type-safe manner. For example, suppose we want a client that can invoke a query of all of the superheroes in a given location. We would create a query interface like this:

@GraphQlClientApi
interface SuperHeroesApi {
    List allHeroesIn(String location);
}

Where SuperHero on the client-side looks like this:

class SuperHero {
    private String name;
    private List superPowers;
}

The SuperHero entity might contain dozens of fields on the server-side, but if we're only interested in the hero's name and superpowers, then we only need those two fields in our client-side class. Now, we can invoke the query with code like this:

SuperHeroesApi api = GraphQlClientBuilder.newBuilder().build(SuperHeroesApi.class);
List heroesOfNewYork = api.allHeroesIn("NYC");

Remember that this client API is not official, but the official MicroProfile GraphQL 1.1 API will be based on it. Think of this as a preview.

Use the built-in GraphiQL UI for faster queries and mutations

Open Liberty now sports a built-in GraphiQL user interface as shown in Figure 1. The new, web-based UI allows you to write and execute GraphQL queries and mutations in real-time with advanced editing features like command completion, query history, schema introspection, and so on.

To enable the UI, you must first write and deploy a MicroProfile GraphQL application. Then add this line to your server.xml:

<variable name="io.openliberty.enableGraphQLUI" value="true" />

You can use a web browser to access the UI, by merely opening your GraphQL application's context root and adding /graphql-ui. As an example, suppose that we use the default port (9080) and our application is namedmyGraphQLApp. In that case, we would access the UI at http://localhost:9080/myGraphQLApp/graphql-ui.

This workaround was resolved in issue #13201.

We want your feedback

As an open source team, we love receiving feedback from Open Liberty users. A recent example is this comment, taken from Open Liberty #13036): "Hello, I am using microprofile-graphql on openliberty and everything goes well except for the exception whitelisting mechanism via microprofile config ..."

Our MicroProfile GraphQL feature has only been generally available for a few months, so it's great to know that users are adopting it. We're also excited that some of you are already exploring the "dark corners" of exception handling and similar features.

While we dislike discovering that we let a bug slip through the cracks, we're eager to fix them when they do. If you find an issue or want to suggest an enhancement that would make your experience with Open Liberty better, please let us know. You can always reach us by opening an issue on GitHub or contacting us on Twitter at @OpenLibertyIO. We're also available to chat online using Gitter and on the Open Liberty Developer Experience page.

Try Open Liberty 20.0.0.8 in Red Hat Runtimes now

Open Liberty is part of the Red Hat Runtimes offering and is available to Red Hat Runtimes subscribers. To learn more about deploying Open Liberty applications to Red Hat OpenShift, see our Open Liberty guide: Deploying microservices to OpenShift.