Ramblings on Web Development and Software Architecture

Posted  4 days ago


Building GraphQL APIs powered by Vert.x, jOOQ & Kotlin - I

This is the first in a series of articles where we explore a JVM based stack comprising of Kotlin, Vert.X and jOOQ for development of GraphQL APIs.

About GraphQL

GraphQL is an application level query language which can, as of this writing, be implemented and consumed in most popular languages.

Quoting from the official site:

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

If you are unfamiliar with GraphQL from a consumer perspective, it might be better to go through the official introduction first. This post assumes user-level familiarity.

GraphQL in Java

When it comes to JVM, graphql-java is one of the most mature GraphQL implementations, and is what we use in this article. However, GraphQL java cares only about the execution of a GraphQL request given a schema and associated handlers. In a realistic application we'd want to expose a GraphQL over an HTTP endpoint. So, it is common to pair graphql-java with a web framework or HTTP handler. Our choice for the latter in the context of this post is Vert.x-Web.

About Vert.X & Vert.X-Web

Vert.X is a toolkit for building event-driven reactive services and Vert.X-web leverages the lower level toolkit for building web applications.

From the official docs:

Vert.x Core

The Vert.x core APIs contain the backbone for writing Vert.x applications and low-level support for HTTP, TCP, UDP, file system, asynchronous streams and many other building blocks. It is also used by many other components of Vert.x.

Vert.x Web

A tool-kit for writing sophisticated modern web applications and HTTP microservices.

As we will see below, Vert.X and graphql-java work very well together because the graphql-java natively supports asynchronous execution strategy which fits perfectly with the asynchronous event-driven style that Vert.X facilitates.

jOOQ for persistence

A real-world application would also need to persist its data, and for that our solution of choice here is jOOQ, a type-safe SQL builder for Java.

jOOQ is commonly used in a database-first first where the database is managed through DB centric tools and the DAO (Data Access Object) layer to interface with the database from application code is generated by introspecting the database.

The generators which come with jOOQ don't support Vert.X out of the box, but the Vert.X core is very flexible and the vertx-jooq project provides code-generation support that bridges the two.

Why this particular combination ?

All three of these libraries, provide low-level control to the developer and don't impose superfluous high level abstractions or indirections that get in the way of performance or debuggability.

So we end up with code that is easy to reason through, does not require us to jump through unnecessary indirections and does not require future maintainers to familiarize themselves with an onerous set of conventions before they can get productive with the stack.

About Kotlin

Lastly, Kotlin is a language from JetBrains that targets (among other platforms) the JVM and has excellent interop with Java. So even though all of the above libraries are written in java, we will be able to use them in Kotlin without any additional wrappers and take advantage of the great tooling support by JetBrains.

I am increasingly leaning towards towards Kotlin for most of my backend work because I find kotlin code to be a great blend of conciseness, readability and type safety. Also, being a part of the wider JVM ecosystem, kotlin lends itself well to scalable performant applications.

Getting our feet wet

The official site recommends using https://start.vertx.io/ as a means to bootstrap our application. This site provides a web interface to generate the scaffold for a java or kotlin application using Vert.X.

However, this generator doesn't completely address the needs for our chosen stack, because while we intend to write application code in Kotlin, the vertx-jooq project generates java code for interfacing with the database and hence we'd want our project to be able to compile both java and kotlin.

Following pom.xml, modelled after the kotlin official recommendations for mixed maven projects, provides us all we need to have a hybrid java & kotlin project:

(Click image to access text snippet)