DRAPI - A Vert.x Success Story

HCL Domino is the latest incarnation of the venerable groupware originally known as Lotus Notes. It is mainly written in C/C++ for its NoSQL database and core functionality, with a Java layer for some of the server functionality. The Domino REST API (DRAPI) is written in Java using Vert.x and sits on top of the core functionality.

Capabilities provided by Vert.x helped to shape DRAPI into a flexible solution meeting diverse customers’ needs and deployment scenarios.

Contract first development

Our team practises contract-first development and uses OpenAPI to define the REST API. Instead of using the OpenAPI specification to generate the server code stubs at compile time, we were looking for the ability to dynamically load specifications in an extensible way, which the Vert.x OpenAPI Router provides.

Based on OpenAPI’s operationId, incoming requests are send on Vert.x EventBus to be processed by the corresponding handler. We use the combination of specification name and operationId to form the EventBus address. This allowed us to separate the web facing code from the database facing code that heavily relies on Jav Native Access (JNA). We use the Swagger UI WebJAR to provide the UI to interact with the API.

Dynamic configuration

On startup, we scout the classpath for configuration files that then are assembled into our Vert.x Config object. This provides us with the ability to tailor deployments to customer needs.

E.g. Don’t need the mail API? Just remove mailapi.jar from your deployment’s /libs folder. Got a spec and code for /specialapi? Just add your jar to the /libs folder and restart the app (In Domino there’s the command tell restapi reload for that).

An OpenAPI specification is run through a filter, with the help of JSON pointers to tailor it to individual deployment needs, switching off undesired endpoints.

EventBus, Verticles and executeBlocking

Incoming request are sent to the EventBus, where they are picked up by the respective verticles. Results are returned to the Eventbus as single or multiple JSON objects, which get returned to the caller using chunked encoding if needed.

The HCL Domino C-API heavily relies on request/response on fixed threads, so we use Vert.x executeBlocking to bridge the event driven and request/response paradigms. Inside the blocking code we use an emit(json) method to send results to the EventBus as they are retrieved from the C API. This ensures that we don’t “block or cross” the “Thread wires”.

How HCL Domino REST API works

Routing & Security

DRAPI not only provides the REST API into Domino, but also can host single page applications (SPA). To ensure their protection, we use the CSP Handler to enforce a Content Security Policy on the SPAs. Not all developers follow a clear separation of HTML, CSS and JavaScript, so we allow different levels of CPS depending on each SPA. The Vert.x Router allows to mount individual CSP policies on each route.

Most of our routes are protected using JWT. To accommodate our customers’ deployment situations, we build our own IdP implementation on top of Vert.x Auth, as well as added support for OIDC using Vert.x OAuth2 auth provider. It has been successfully tested with both Keycloak and Microsoft Entra ID (formerly known as MS Azure Active Directory).

There’s more

We take advantage of Vert.x Micrometer integration as well as the support for health checks. The micrometer statistics allow not only to monitor general API health and performance, but also provide insights into the utilization of individual Domino databases.

Our clients have very diverse ideas about how to deal with TLS, termination and certificates. Vert.x flexible TLS support allows us to cater to these ideas.

Vert.x router can handle HTTP methods like PROPFIND, LOCK or UNLOCK that are not part of the regular HTTP specification. This allowed us to build WebDAV and WOPI support into DRAPI, which enables seamless Office document handling.

Last but not least, Vert.x Scheduler keeps our IdP certificates updated.