vertx-rest

Overview
Setup
How to use
- Rest Verticle
- JAX-RS Routes
Validations
Exception Handling
Dependency Injection
Custom Providers
Timeouts
Examples
Swagger
References

Overview

Abstraction over resteasy-vertx to simplify writing a vertx REST application based on JAX-RS annotations
Provides a backpressure enabled HTTP server to drop requests on high load
Exception mappers to standardise error response
Timeout annotation for closing long-running requests
Uses rxjava3

Setup

Add the following dependency to the dependencies section of your build descriptor:

Maven (in your pom.xml):

<dependency>
  <groupId>com.dream11</groupId>
  <artifactId>vertx-rest</artifactId>
  <version>x.y.z</version>
</dependency>

Gradle (in your build.gradle file):

dependencies {
 compile 'com.dream11:vertx-rest:x.y.z'
}

Note: Replace x.y.z above with one of the released versions

Usage

Create Rest Verticle

Create the application REST Verticle by extending com.dream11.rest.AbstractRestVerticle class. The AbstractRestVerticle here does the following:

Finds all the resources(i.e, classes annotated with @Path) in the package and adds an instance of each of the resource classes to the resteasy-deployment registry
Adds all the Filters and ExceptionMappers and any other custom Providers to the resteasy-deployment
Starts a backpressure enabled HTTP server and dispatches each request to the handler registered with the resteasy-deployment

public class RestVerticle extends AbstractRestVerticle {
    
  public RestVerticle() {
    // starts http server with default options
    // All classes with @Path annotation in the specified package are registered with the router
    super("com.dream11.package"); 
  }
  
  @Override
  protected ClassInjector getInjector() {
    // Add your implmentation of injector
    return null;
  }
}

Use the following constructor to pass custom HTTP Server Options

public RestVerticle() {
  super("com.dream11.package", new HttpServerOptions().setPort(8080)); // starts http server with provided options
}

Create a Rest Resource

@Path("/test")
public class TestRoute {

  @GET
  @Consumes(MediaType.WILDCARD)
  @Produces(MediaType.APPLICATION_JSON)
  @ApiResponse(content = @Content(schema = @Schema(implementation = String.class)))
  public CompletionStage<String> test() {
    return Single.just("Hello World")
            .toCompletionStage();
  }
}

Validations

Use all the jakarta constraints given here
You can use @TypeValidationError(code=<errorCode>, message=<errorMessage>) on DTO parameters to send custom error code and message when parsing of parameter fails
@TypeValidationError can also be used for Integer, Long, Float or Double types in @HeaderParam, @QueryParam etc. If you want to use @TypeValidationError on a parameter of type other than these types you can create a custom converter similar to IntegerParamConverter and a provider extending ParamConverterProvider. Reference

Exception Handling

Provides exceptions and exception mappers to standardize error response
Implement RestError as an enum to specify error codes, messages and http status codes to be returned in response for your exceptions
- Throw RestException with the restError to return error response in the following format
```
{
"error": {
  "code": "UNKNOWN_EXCEPTION",
  "message": "Something went wrong",
  "cause": "Cannot connect to mysql database"
} 
}
```
Refer to the package com.dream11.rest.exception.mapper for mappers provided by default
Implement your own exception mappers if you need some other error response

Timeouts

Configure request timeout by annotating your JAX-RS resource classes with `@Timeout(value = , httpStatusCode = )`
Default timeout for each JAX-RS route is 20 seconds
Since there is no official HTTP Status code for origin server timeout, it has been kept configurable. By default 500 status code is returned in case of timeouts.

Dependency Injection

Implement abstract method getInjector of AbstractRestVerticle to return an implementation of the ClassInjector interface
This will be used for injecting instances of the REST resource classes
Refer to com.dream11.rest.injector.GuiceInjector for an example

Custom Providers

Annotate your provider classes with @Provider to automatically register them with resteasy deployment

Alternatively, if your provider class necessitates a constructor with parameters, you can override the following method in AbstractRestVerticle to register the provider object

public class RestVerticle extends AbstractRestVerticle {

@Override
protected List<Object> getProviderObjects() {
  List<Object> providerObjects = super.getProviderObjects();
  // add your provider object with custom constructor to the list
  return providerObjects;
}
}

Custom Json Provider

You can create custom json providers by

Implement the JsonProvider interface, defined in JsonProvider and then,

Override the following method in AbstractRestVerticle

public class RestVerticle extends AbstractRestVerticle {
  
@Override
protected JsonProvider getJsonProvider() {
  // return your custom json provider
}
}