Chapter 11: MicroProfile GraphQL

GraphQL is a distributed query language that addresses some of the shortcomings of REpresentational State Transfer (REST). In particular, GraphQL addresses the notions of over-fetching (receiving more data than the client intended) and under-fetching (requiring the client to make multiple requests to get the data it requires). GraphQL applications make use of a schema file that presents clients with the queries and mutations at its disposal, as well as the entities it can access and manipulate.

The ease of use and robustness of GraphQL explains why its popularity is growing, especially in cloud-native applications. MicroProfile GraphQL (MP GraphQL) makes it easy to create GraphQL-based applications.

In this chapter, we're going to cover the following main topics:

• Understanding GraphQL basics and when to use it
• Building services with MP GraphQL
• Consuming GraphQL services with client application programming interfaces (APIs...

Technical requirements

To build and run the samples mentioned in this chapter, you will need a Mac or PC (Windows or Linux) with the following software:

• Java Development Kit (JDK) version 8 or higher (http://ibm.biz/GetSemeru)
• Apache Maven (https://maven.apache.org/)
• A Git client (https://git-scm.com/)

All of the source code used in this chapter is available on GitHub at https://github.com/PacktPublishing/Practical-Cloud-Native-Java-Development-with-MicroProfile/tree/main/Chapter11.

Once you have cloned the GitHub repository, you can start the Open Liberty server where these code samples will execute by entering the Chapter11 directory and executing the following command from the command line:

 mvn clean package liberty:run

You can then stop the server in the same command window by pressing Ctrl + C.

Now we've got the prerequisites taken care of, let's start by learning the basics of GraphQL.

Understanding GraphQL basics and when to use it

As with REST, GraphQL is a means of accessing and modifying remote data over web-based transports. It uses a publicly visible schema, allowing clients to know exactly which entities it can query, which fields can be modified, and so on. This is similar to how OpenAPI describes RESTful APIs. The schema acts as a contract between the client and the service. GraphQL strictly enforces the schema, preventing clients from accessing or modifying entities or fields that are not defined within it. This strictness provides a lot of freedom for developers of both clients and services, which we'll cover later in this section.

GraphQL supports the following operations:

• Queries: Queries are read operations and are analogous to GET requests in REST.
• Mutations: Mutations are used for modifying data—that is, creating, updating, and/or deleting it.
• Subscriptions: Subscriptions are used so that clients can receive notifications...

Building services with MP GraphQL

In this section, we will learn how to develop a GraphQL application using the MP GraphQL APIs and runtime framework. We'll cover building queries and mutations, and how to invoke them using an interactive web tool called GraphiQL. We'll also cover entities and enumerated types. Finally, we'll cover a technique to reduce unnecessary server-side computations and deliver partial results.

Most GraphQL APIs for Java require you to write a schema first and then build the Java code around it. This approach tends to cause some level of dual maintenance, and it can slow down development as you evolve your application. MP GraphQL uses a code-first approach, meaning that you write the code using patterns similar to Jakarta RESTful Web Services (JAX-RS), and the framework generates the schema at runtime. This makes development and maintenance faster and easier. Let's start by building a basic Hello World query service.

Developing queries...

Consuming GraphQL services with client APIs

The client APIs are not officially part of the MP GraphQL specification yet. At the time of writing, these APIs are still under development in the SmallRye GraphQL project, with the intention of formalizing them into the specification.

Disclaimer

Since these APIs are not official yet, they are subject to change. The information in this section pertains to the SmallRye GraphQL version 1.2.3 client APIs. These APIs may change when added to the official MP GraphQL specification, so please check with the official documentation at https://github.com/eclipse/microprofile-graphql for any changes.

The MP GraphQL project intends to support two flavors of client APIs. Similar to the JAX-RS client and the MicroProfile REST client (see Chapter 4, Developing Cloud-Native Applications), there is a dynamic client API and a type-safe client API. As with the JAX-RS client, the dynamic client allows users to specify the nitty-gritty details of the...

Summary

In this chapter, we've learned about GraphQL and how it addresses some of the gaps in REST. We've also learned how to create and consume GraphQL services using MP GraphQL, without the overhead of maintaining a schema in addition to Java code. We've learned that we can build queries and mutations by applying annotations to our API classes and that we can enrich them by adding descriptions, parameters, formatting, and more. By outsourcing, we've learned that we can avoid executing expensive operations when they are not necessary. We've also learned how to send partial results when exceptions occur. We've learned that there are some useful tools such as GraphiQL that can simplify testing. And while the client APIs aren't fully supported from the specification, we've been able to view two different clients, and we've seen how we could use them for integration testing or to consume GraphQL services.

With what we've learned in...