Implementing Validation for RESTful Services with Spring Boot

This guide will help you implement effective validations for a REST API/Service with Spring Boot.

You will learn

• What is validation?
• Why do you need validation?
• What is Hibernate Validator?
• What is Bean Validation API?
• What are the default validation capabilities provided by Spring Boot?
• How to implement validation with Spring Boot?
• How to implement validation with Bean Validation API?

Project Code Structure

Following files contain the important components of the project we will create. A few details:

• SpringBoot2RestServiceApplication.java - The Spring Boot Application class generated with Spring Initializer. This class acts as the launching point for application.
• pom.xml - Contains all the dependencies needed to build this project. We will use Spring Boot Starter AOP.
• Student.java - Student JPA Entity
• StudentRepository.java - Student JPA Repository. This is created using Spring Data JpaRepository.
• StudentResource.java - Spring Rest Controller exposing all services on the student resource.
• CustomizedResponseEntityExceptionHandler.java - Component to implement global exception handling and customize the response based on the exception type.
• ErrorDetails.java - Response Bean to use when exceptions are thrown from API.
• StudentNotFoundException.java - Exception thrown from resources when student is not found.
• data.sql - Initial data for the student table. Spring Boot would execute this script after the tables are created from the entities.

Tools you will need

• Maven 3.0+ is your build tool
• Your favorite IDE. We use Eclipse.
• JDK 1.8+

What is Validation?

You expect a certain format of request for your RESTful Service. You except the elements of your request to have certain data types, certain domain constraints.
What if you get a request not meeting this constraints?
Think. What should you do?
Can I just return a generic message Something went wrong.. Is that good enough?
One of the core design principles for RESTful services is

Think about the consumer

o, what should you do when something in the request is not valid.
You should return a proper error response

• Clear message indicating what went wrong? Which field has an error and what are the accepted values? What the consumer can do to fix the error?
• Proper Response Status Bad Request.
• Do not include sensitive information in the response.

Response Statuses for Validation Errors

Recommended response status for validation error is -> 400 - BAD REQUEST

Bootstrapping a Project with REST Resouce

In the previous article in the series - http://www.springboottutorial.com/spring-boot-crud-rest-service-with-jpa-hibernate, we set up a simple restful service with a resource exposing CRUD methods.

Default Validation with Spring Boot

Spring Boot provides good default implementation for validation for RESTful Services. Let’s quickly look at the default Exception Handling features provided by Spring Boot.

Wrong Content Type

If you use Content-Type as application/xml and this is not supported by your application, Spring Boot by default returns a response status of 415 - Unsupported Media Type

Invalid JSON Content

If you send a invalid JSON content to a method expecting a body, you would get a 400 - Bad Request

Valid JSON with Missing Elements

However, if you send a valid JSON structure with missing/invalid attributes/elements, application will execute the request with what ever data is available.
Following request executes with a status of -> 201 Created
POST http://localhost:8080/students
Empty Request Content

{
  
}

Following request executes with a status of -> 201 Created
POST http://localhost:8080/students
Request Content

{
    "name1": null,
    "passportNumber": "A12345678"
}

You can notice that the above request has an invalid attribute name1.

This is the response when you fire a GET to http://localhost:8080/students
[ { “id”: 1, “name”: null, “passportNumber”: null }, { “id”: 2, “name”: null, “passportNumber”: “A12345678” }, { “id”: 10001, “name”: “Ranga”, “passportNumber”: “E1234567” }, { “id”: 10002, “name”: “Ravi”, “passportNumber”: “A1234568” } ]

You can see that both the resources were created with ids 1 and 2 with nulls for values that were not available. Invalid elements/attributes are ignored.

Customizing Validations

To customize the validation, we will use Hibernate Validator, which is one of the implementations of the bean validation api.
We get Hibernate Validator for free when we use Spring Boot Starter Web.
So, we can get started with implementing the validations.

Implementing Validations on the Bean

Let’s add a few validations to the Student bean. We are using @Size to specify the minimum length and also a message when a validation error occurs.

@Entity
public class Student {
  @Id
  @GeneratedValue
  private Long id;
  
  @NotNull
  @Size(min=2, message="Name should have atleast 2 characters")
  private String name;
  
  @NotNull
  @Size(min=7, message="Passport should have atleast 2 characters")
  private String passportNumber; 

Bean Validation API provides a number of such annotations. Most of these are self explanatory.

• DecimalMax
• DecimalMin
• Digits
• Email
• Future
• FutureOrPresent
• Max
• Min
• Negative
• NegativeOrZero
• NotBlank
• NotEmpty
• NotNull
• Null
• Past
• PastOrPresent
• Pattern
• Positive
• PositiveOrZero

Enabling Validation on the Resource

Simple. Add @Valid in addition to @RequestBody.


That’s it.
When you execute a request with attributes not matching the constraint, you get a 404 BAD Request status back.
Request

{
    "name": "",
    "passportNumber": "A12345678"
  }

But the problem is that there are no details returned indicating what went wrong.

• The consumer knows its a bad request.
• But, how do they no what is wrong? Which element did not pass the validation? What should the consumer do to fix it?

Customizing Validation Response

Let’s define a simple error response bean.

public class ErrorDetails {
  private Date timestamp;
  private String message;
  private String details;

  public ErrorDetails(Date timestamp, String message, String details) {
    super();
    this.timestamp = timestamp;
    this.message = message;
    this.details = details;
  }

Let’s now define a @ControllerAdvice to handle validation errors. We do that by overriding handleMethodArgumentNotValid(MethodArgumentNotValidException ex, HttpHeaders headers, HttpStatus status, WebRequest request) method in the ResponseEntityExceptionHandler.

 

@ControllerAdvice
@RestController
public class CustomizedResponseEntityExceptionHandler extends ResponseEntityExceptionHandler {

  @Override
  protected ResponseEntity

 

 To use ErrorDetails to return the error response, let’s define a ControllerAdvice as shown below.

@ControllerAdvice
@RestController
public class CustomizedResponseEntityExceptionHandler extends ResponseEntityExceptionHandler {

  @ExceptionHandler(StudentNotFoundException)
  public final ResponseEntity handleUserNotFoundException(StudentNotFoundException ex, WebRequest request) {
    ErrorDetails errorDetails = new ErrorDetails(new Date(), ex.getMessage(),
        request.getDescription(false));
    return new ResponseEntity<>(errorDetails, HttpStatus.NOT_FOUND);
  }

When you execute a request with attributes not matching the constraint, you get a 404 BAD Request status back.
Request

{
    "name": "",
    "passportNumber": "A12345678"
  }

You also get a Response Body indicating what is wrong!

 {
  "timestamp": 1512717715118,
  "message": "Validation Failed",
  "details": "org.springframework.validation.BeanPropertyBindingResult: 1 errors\nField error in object 'student' on field 'name': rejected value []; codes [Size.student.name,Size.name,Size.java.lang.String,Size]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [student.name,name]; arguments []; default message [name],2147483647,2]; default message [Name should have atleast 2 characters]"
}

http://www.springboottutorial.com/spring-boot-crud-rest-service-with-jpa-hibernate