Spring Boot REST – request validation

Creating REST endpoints has become pretty popular. All these microservices, APIs, simple backend applications for the frontend javascript apps often use REST for communication. But sometimes, requests that are made toward them may have errors. Bad format, missing required values, missing properties. How to handle it? Let’s see.

All the above errors are pretty simple most of the time,  but nevertheless, they can cause trouble in the business logic and we have to protect our services from them. The best solution here is to fail fast, that is to validate the request as soon as possible, check everything we can when it comes to the request format, and if it is wrong, return an error before we hit our business logic with the request. We have to ensure that all requests that are coming into it are valid. The approach like this gives us two things. First, we do not bother our services with requests that cannot succeed anyway. The second thing is that we can remove a lot of sanity checks from business logic, we can assume that all the data will be correct, everything that is required will be there. This simplifies the code a lot.

Simple validation

Spring offers the simplest form of validation out of the box. When you define a REST endpoint and it’s PathVariable or RequestParameter we can specify if a particular parameter is required or not. Both are required by default but we can easily change it to optional:

With these simple annotations, Spring will validate all requests, and respond with 400 Bad Request when the required parameter is missing or has a wrong type. For example, if we declare a parameter as an Integer, and we will pass some kind of String in the request, we will also receive an error response.

Request body validation

When it comes to validation a request body with some complex objects that represent a parsed JSON we have to do a bit more.

First, we have to annotate our object with all the constraints and requirements. Spring has built-in support for JSR 303 Bean Validation which makes it really easy. We just annotate our fields, with NotNull, Max, Min, Pattern annotations with desired parameters. If we have some nested objects there, we have to add Valid annotation on a field with this objects, so that it will be validated.

Here’s a simple example of adding a null check to the fields:

And on the controller endpoint we add the Valid annotation:


Custom validators

JSR 303 Validation gives a pretty broad set of validators out of the box. We can check string lengths, number max and min values, use regular expressions etc. But sometimes, we have a need for a specific kind of validation. That’s when we have to write our own validator and annotation.

For validator, we have to implement ConstraintValidator interface, we define an initialize method that is used to read parameters from annotations and isValid method that performs the validation. As you can see, this validation checks if given Integer value is in specified range:

Annotations are also really simple, we have to specify the validator class using Constraint annotation, and define available parameters, their default values, and default error message:

Now, we can just put InRange annotation on our field. And that’s it. Simple and readable.

Complex, conditional validation

There are sometimes cases, where a simple field by field validation is not enough. Sometimes we have to check field values depending on other field value. This is also possible to do.

Let’s say that we want to check an address. Let’s say that name cannot be empty and if it is a company address, company taxId has to be provided.

Annotation is as simple as before:

But our validator is a bit more complex as it got more logic inside:

Most complexity above comes from the definition of custom error messages on each error. Using only one error message for complex multi-field validation is not a good practice. To add a custom error message in the validator, first, we have to disable a default error message with disableDefaultConstraintViolation() method. Then we can add our messages and even describe on which field the error has occurred.

Different validation for different endpoint

Another case of validation is that we can use the same objects in different contexts. For example for creating and updating. For updating, we would require a nonnull id of the object. For creating id should be null. We can achieve this using groups parameter in JSR303 annotations. The idea is, that we define few groups, as interfaces without methods. Then, for each annotation, we set group or groups for which this annotation should be active.

Here’s a simple example:

Now, we have to tell spring, which group to use. We do this with Validated annotation, instead of the Valid annotation:


Custom error response

Ok, we can now detect all kind of errors. But it would be good to tell the other guy what’s wrong and simple status code and one line message may not be enough or we may want to return it as JSON in our own format. For this, we can add an error handling to our controllers.

Above you can see, that we are "catching" here an exception thrown by the JSR303 validation, extract all the field errors, grab the first one and build our own response object that will be later serialized to JSON and returned in the response.


Adding validation to Spring controllers is a breeze. You don’t have to create your own framework that does this, everything is built-in and ready to use and what’s important, is that it is also very easy to extend and customize it to the needs of a project.

You can find the above example code in my GitHub repository https://github.com/lmonkiewicz/spring-rest-validation

Also published on Medium.