Java Rest API on Vert.x

Question

I'm developing REST API service based on Java and Eclipse Vert.x framework. I didn't use Vert.x previously and I faced with such architectural issue. When I need to implement API for few REST resources (for example, users and products) should I created separate verticles for each resource?

For instance, when I implemented some REST API using Jersey, I created separate resource classes (for our example it could be UsersResource and ProductsResource classes). In each class I implemented allowed actions (e.g. CRUD operations) and mapped them to REST methods (like GET, POST, etc). But should I implement it in a similar way when I work with Vert.x (create UsersVerticle and ProductsVerticle), or does it have some other ideological approach?

Answer 1

The answer is, it depends. Generally, the Router/web server would be a single verticle and the implementation code would be in one or more other verticles. A better approach is to use the Service Proxy capability though. This will allow you to more clearly define your API without as much hand wiring of event bus endpoints. Have a look at https://github.com/rhoar-shootout/rhoar-vertx to see a good example.

EDIT - Things have moved on and changed

Now, there are better tools for using Service Proxies with Vert.x Router. I would recommend using the new OpenAPI3RouterFactory along with an OpenAPI specification file. In conjunction with the vertx-starter tool, you can generate the Service Proxies AND the OpenAPI3Router code from the specification file.

Answer 2

I recommend to create a single RestAPIVerticle and use a Router within that Verticle to setup your routes. You can however modularize your routes by creating classes and package routes for specific tasks together. But always use a dedicated Router/Routes for your RestAPIVerticle.

Sharing routes or handlers across multiple Verticles is a bad idea because it violates the thread safety model of Vert.x. Most handlers are not (and must not be) threadsafe and thus you could get into trouble when sharing routes or handlers between Verticles.

If you need to handle more requests you can easily deploy another instance of your Verticle.

I use the process described for Gentics Mesh which uses Vert.x to provide a REST API. I summarized the workflow here: https://getmesh.io/docs/beta/contributing.html#_big_picture

Sources are also on Github.

Another option is of course to generate your implementation from an REST specification (Contract driven design). I think there is an article on the Vert.x blog which describes this process.