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 = <timeoutMillis>, httpStatusCode = <httpStausCode>)
• 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
  }
}

Examples

Please refer tests for an example application

Swagger Specification

Follow this doc to generate swagger specification.

References

• Swagger Maven Plugin
• Resteasy Vertx
• Hibernate Validations
• Jakarta Validation Constraints
• JAX-RS
• Swagger Annotations