Building Reactive REST API with Vert.x

29 Mar, 2023 | 3 minutes read

What is Eclipse Vert.x?

Vert.x is an open source, reactive software development toolkit from the developers of Eclipse. Reactive programming is a programming paradigm, associated with asynchronous streams, which responds to any changes or events.

Vert.x supports multiple JVM and non-JVM languages like:

  • Java
  • Groovy
  • Ruby
  • Python
  • JavaScript

There are two ways to start a Vert.x project: 1) go to or add the following dependency to a Maven project:

Building Reactive REST API with Vert.x


The components in Vert.x are called Verticles. Verticles are pieces of code that Vert.x engine executes. Vert.x provides an abstract vertical class which can be extended and implemented. Once we extend the AbstractVerticle class we must implement the start method which is called when we deploy the verticle. The start method will be executed immediately when we deploy the Verticle. Deploying Verticles can be achieved through Vertex objects.

Building Reactive REST API with Vert.x

The start method has one argument which is a promise and on the end of the implementation we have to either call .complete() method if everything worked as it should, or .fail() if something went wrong. Once we run the application, the code will write “Deployed MainVerticle” on the console.

Event Bus

A Vert.x application is made up of one or more verticles, and each verticle forms a unit for processing asynchronous events. When we need to work with multiple verticles in our applications then we also need communication between these verticles. Verticles communicate with each other by sending messages on the event bus.

Building REST API

To start building REST API we need to add the web dependency of Vert.x.

Building Reactive REST API with Vert.x

First, we need to create the HTTP server with the following code:

Building Reactive REST API with Vert.x

You can see that at the request handler method, we are providing a router. In the router, we map the REST Endpoints to methods that will return the data.

Building Reactive REST API with Vert.x

We can obtain the Router object from the static method Router.router() and as argument we need to pass the Vert.x object. Then in the router, we have the methods for the HTTP Methods (GET,POST,PUT,DELETE .. etc.) and we can define a handler for that endpoint. Then in the handler, we have the corresponding methods, for example, the create method:

Building Reactive REST API with Vert.x

From the RoutingContext we can obtain the request body as JSON and it will map it to the Book class. We can see that this method returns a Future from the bookService. In the Book Service, we have a method created that accepts the Book as an argument and sends it to the repository to insert the book into the database.

Book Service:

Building Reactive REST API with Vert.x

Book Repository:

To update/save/delete the database we use the SqlTemplate.forUpdate method, and to retrieve data we use the forQuery method. In this project, we are using PostgreSQL as a database in docker, and flyway for managing migrations on the database.


Create Book

HTTP POST -> http://localhost:8085/api/v1/books


Get All Books

HTTP GET -> http://localhost:8085/api/v1/books



In this article, we delved into the Vert.x toolkit and its capabilities, including a demonstration of how to create a basic REST API with it. If you’re interested in exploring the project further, the source code is available on GitHub: