Validation for Functional Endpoints in Spring

1. Overview

It’s often useful to implement input validation for our APIs to avoid unexpected errors later when we’re processing the data.

Unfortunately, in Spring 6 there’s no way to run validations automatically on functional endpoints as we do on annotated-based ones. We have to manage them manually.

Still, we can make use of some useful tools provided by Spring to verify easily and in a clean manner that our resources are valid.

2. Using Spring Validations

Let’s start by configuring our project with a working functional endpoint before diving into the actual validations.

Imagine we have the following RouterFunction:

@Bean
public RouterFunction<ServerResponse> functionalRoute(
  FunctionalHandler handler) {
    return RouterFunctions.route(
      RequestPredicates.POST("/functional-endpoint"),
      handler::handleRequest);
}

This router uses the handler function provided by the following controller class:

@Component
public class FunctionalHandler {

    public Mono<ServerResponse> handleRequest(ServerRequest request) {
        Mono<String> responseBody = request
          .bodyToMono(CustomRequestEntity.class)
          .map(cre -> String.format(
            "Hi, %s [%s]!", cre.getName(), cre.getCode()));
 
        return ServerResponse.ok()
          .contentType(MediaType.APPLICATION_JSON)
          .body(responseBody, String.class);
    }
}

As we can see, all we’re doing in this functional endpoint is formatting and retrieving the information we received in the request body, which is structured as a CustomRequestEntity object:

public class CustomRequestEntity {
    
    private String name;
    private String code;

    // ... Constructors, Getters and Setters ...
    
}

This works just fine, but let’s imagine that we now need to check that our input complies with some given constraints, for example, that none of the fields can be null and that the code should’ve more than 6 digits.

We need to find a way of making these assertions efficiently and, if possible, separated from our business logic.

2.1. Implementing a Validator

As it’s explained in this Spring Reference Documentation, we can use the Spring’s Validator interface to evaluate our resource’s values:

public class CustomRequestEntityValidator 
  implements Validator {

    @Override
    public boolean supports(Class<?> clazz) {
        return CustomRequestEntity.class.isAssignableFrom(clazz);
    }

    @Override
    public void validate(Object target, Errors errors) {
        ValidationUtils.rejectIfEmptyOrWhitespace(
          errors, "name", "field.required");
        ValidationUtils.rejectIfEmptyOrWhitespace(
          errors, "code", "field.required");
        CustomRequestEntity request = (CustomRequestEntity) target;
        if (request.getCode() != null && request.getCode().trim().length() < 6) {
            errors.rejectValue(
              "code",
              "field.min.length",
              new Object[] { Integer.valueOf(6) },
              "The code must be at least [6] characters in length.");
        }
    }
}

We won’t go into details about how the Validator works. It’s enough to know that all the errors are collected when validating an object – an empty error collection means that the object adheres to all our constraints.

So now that we have our Validator in place, we’ll have to explicitly call it’s validate before actually executing our business logic.

2.2. Executing the Validations

At first, we can think that using a HandlerFilterFunction would be suitable in our situation.

But we have to keep in mind that in those filters -same as in the handlers- we deal with asynchronous constructions -such as Mono and Flux.

This means that we’ll have access to the Publisher (the Mono or the Flux object) but not to the data that it will eventually provide.

Therefore, the best thing we can do is validate the body when we are actually processing it in the handler function.

Let’s go ahead and modify our handler method, including the validation logic:

public Mono<ServerResponse> handleRequest(ServerRequest request) {
    Validator validator = new CustomRequestEntityValidator();
    Mono<String> responseBody = request
      .bodyToMono(CustomRequestEntity.class)
      .map(body -> {
        Errors errors = new BeanPropertyBindingResult(
          body,
          CustomRequestEntity.class.getName());
        validator.validate(body, errors);

        if (errors == null || errors.getAllErrors().isEmpty()) {
            return String.format("Hi, %s [%s]!", body.getName(), body.getCode());
        } else {
            throw new ResponseStatusException(
              HttpStatus.BAD_REQUEST,
              errors.getAllErrors().toString());
        }
    });
    return ServerResponse.ok()
      .contentType(MediaType.APPLICATION_JSON)
      .body(responseBody, String.class);
}

In a nutshell, our service will now retrieve a ‘Bad Request‘ response if the request’s body doesn’t comply with our restrictions.

Can we say we achieved our objective? Well, we’re almost there. We’re running the validations, but there are many drawbacks in this approach.

We are mixing the validations with business logic, and, to make things worse, we’ll have to repeat the code above in any handler where we want to carry our input validation.

Let’s try to improve this.

3. Working on a DRY Approach

To create a cleaner solution we’ll start by declaring an abstract class containing the basic procedure to process a request.

All the handlers that need input validation will extend this abstract class, so as to reuse its main scheme, and therefore following the DRY (don’t repeat yourself) principle.

We’ll use generics so as to make it flexible enough to support any body type and its respective validator:

public abstract class AbstractValidationHandler<T, U extends Validator> {

    private final Class<T> validationClass;

    private final U validator;

    protected AbstractValidationHandler(Class<T> clazz, U validator) {
        this.validationClass = clazz;
        this.validator = validator;
    }

    public final Mono<ServerResponse> handleRequest(final ServerRequest request) {
        // ...here we will validate and process the request...
    }
}

Now let’s code our handleRequest method with the standard procedure:

public Mono<ServerResponse> handleRequest(final ServerRequest request) {
    return request.bodyToMono(this.validationClass)
      .flatMap(body -> {
        Errors errors = new BeanPropertyBindingResult(
          body,
          this.validationClass.getName());
        this.validator.validate(body, errors);

        if (errors == null || errors.getAllErrors().isEmpty()) {
            return processBody(body, request);
        } else {
            return onValidationErrors(errors, body, request);
        }
    });
}

As we can see, we’re using two methods that we have not created yet.

Let’s define the one invoked when we have validation errors first:

protected Mono<ServerResponse> onValidationErrors(
  Errors errors,
  T invalidBody,
  ServerRequest request) {
    throw new ResponseStatusException(
      HttpStatus.BAD_REQUEST,
      errors.getAllErrors().toString());
}

This is just a default implementation though, it can be easily overridden by the child classes.

Finally, we’ll set the processBody method undefined -we’ll leave it up to the child classes to determine how to proceed in that case:

abstract protected Mono<ServerResponse> processBody(
  T validBody,
  ServerRequest originalRequest);

There are a few aspects to analyze in this class.

First of all, by using generics the child implementations will have to explicitly declare the type of content they’re expecting and the validator that will be used to evaluate it.

This also makes our structure robust, since it limits our methods’ signatures.

On runtime, the constructor will assign the actual validator object and the class used to cast the request body.

We can have a look at the complete class in the source project.

Let’s now see how we can benefit from this structure.

3.1. Adapting Our Handler

The first thing we’ll have to do, obviously, is extending our handler from this abstract class.

By doing that, we’ll be forced to use the parent’s constructor and to define how we’ll handle our request in the processBody method:

@Component
public class FunctionalHandler
  extends AbstractValidationHandler<CustomRequestEntity, CustomRequestEntityValidator> {

    private CustomRequestEntityValidationHandler() {
        super(CustomRequestEntity.class, new CustomRequestEntityValidator());
    }

    @Override
    protected Mono<ServerResponse> processBody(
      CustomRequestEntity validBody,
      ServerRequest originalRequest) {
        String responseBody = String.format(
          "Hi, %s [%s]!",
          validBody.getName(),
          validBody.getCode());
        return ServerResponse.ok()
          .contentType(MediaType.APPLICATION_JSON)
          .body(Mono.just(responseBody), String.class);
    }
}

As we can appreciate, our child handler is now much simpler than the one we obtained in the previous section, since it avoids messing with the actual validation of the resources.

4. Support to Bean Validation API Annotations

With this approach, we can also take advantage of the powerful Bean Validation’s annotations provided by the javax.validation package.

For example, let’s define a new entity with annotated fields:

public class AnnotatedRequestEntity {
 
    @NotNull
    private String user;

    @NotNull
    @Size(min = 4, max = 7)
    private String password;

    // ... Constructors, Getters and Setters ...
}

We can now simply create a new handler injected with the default Spring Validator provided by the LocalValidatorFactoryBean bean:

public class AnnotatedRequestEntityValidationHandler
  extends AbstractValidationHandler<AnnotatedRequestEntity, Validator> {

    private AnnotatedRequestEntityValidationHandler(@Autowired Validator validator) {
        super(AnnotatedRequestEntity.class, validator);
    }

    @Override
    protected Mono<ServerResponse> processBody(
      AnnotatedRequestEntity validBody,
      ServerRequest originalRequest) {

        // ...

    }
}

We have to keep in mind that if there are other Validator beans present in the context, we might have to explicitly declare this one with the @Primary annotation:

@Bean
@Primary
public Validator springValidator() {
    return new LocalValidatorFactoryBean();
}

5. Conclusion

To summarize, in this post we’ve learned how to validate input data in Spring 5 functional endpoints.

We created a nice approach to handle validations gracefully by avoiding mingling its logic with the business one.

Of course, the suggested solution might not be suitable for just any scenario. We’ll have to analyze our situation and probably adapt the structure to our needs.