Routing operation exposed via Event Bus

[tomaszmichalak]

Vert.x API Contract allows to define operations that are consumed by event bus handlers. This functionality comes from https://vertx.io/docs/vertx-web-api-service/java/. This issue is about defining and implementing this new functionality.

[tomaszmichalak]

See https://github.com/vert-x3/vertx-examples/tree/master/web-api-service-example.

[tomaszmichalak]

Additional references here: https://vertx.io/blog/vert-x-web-api-service-introduction/

[tomaszmichalak]

Analysis

In a typical Vert.x application, when you receive a request to your router, you would forward it to an event bus endpoint that performs some actions and sends the result back to the operation handler.

This makes the encapsulation of the service logic easy to achieve. The class that implements the interface is exposed via Event Bus, and its methods correspond with operations defined in the Open API spec configuration. This allows you to create an interface in the form of:

@WebApiServiceGen
public interface MyService {
  void get(...);
  void create(...);
  void update();
  void delete();
}

Scalability

Each service implementation is exposed with a dedicated Verticle. This allows us to define more instances of the same service that listen on a specific address (Vert.x provides load balancing ootb).

Use cases

With this approach we need to serialize all request (think about streams) data and send it via Event Bus. It fits well REST API interfaces but make it more complicated when we define more complex endpoints. So the current implementation (with io.knotx.server.api.handler.RoutingHandlerFactory) is valid and allows to define Handlers in the form of chain.

Problems

We need to make sure that we do not register routing handlers when x-vertx-event-bus is defined. Additionally we need to verify how we can define failure handlers for those services.

Example

The example interface should be a part of https://github.com/Knotx/knotx-example-project.

[marcinus]

@tomaszmichalak should this issue be closed by now?