{"id":13247,"date":"2013-05-28T16:00:48","date_gmt":"2013-05-28T13:00:48","guid":{"rendered":"http:\/\/www.javacodegeeks.com\/?p=13247"},"modified":"2013-06-13T18:21:50","modified_gmt":"2013-06-13T15:21:50","slug":"spring-from-the-trenches-adding-validation-to-a-rest-api","status":"publish","type":"post","link":"https:\/\/www.javacodegeeks.com\/2013\/05\/spring-from-the-trenches-adding-validation-to-a-rest-api.html","title":{"rendered":"Spring from the Trenches: Adding Validation to a REST API"},"content":{"rendered":"

I am a bit ashamed to admit this but until yesterday, I had no idea that I can add validation to a REST API by using the @Valid<\/em> and the @RequestBody<\/em> annotations. This was not working in Spring MVC 3.0 and for some reason I had not noticed that the support for this was added in Spring MVC 3.1<\/a>. I never liked the old approach because I had to<\/p>\n

    \n
  1. Inject the Validator<\/em> and MessageSource<\/em> beans to my controller so that I can validate the request and fetch the localized error messages if the validation fails.<\/li>\n
  2. Call the validation method in every controller method which input must be validated.<\/li>\n
  3. Move the validation logic into a common base class which is extended by the controller classes.<\/li>\n<\/ol>\n

    When I noticed that I don\u2019t have to do these things anymore, I decided to write this blog post and share my findings with all of you.<\/p>\n

    Note:<\/strong> If we want to use the JSR-303 backed validation with Spring Framework, we have to add a JSR-303 provider to our classpath. The example applications of this blog post use Hibernate Validator 4.2.0 which is the reference implementation of the Bean Validation API (JSR-303).<\/p>\n

    Let\u2019s start by taking a look at the DTO class used in this blog post. The source code of the CommentDTO<\/em> class looks as follows:<\/p>\n

    import org.hibernate.validator.constraints.Length;\r\nimport org.hibernate.validator.constraints.NotEmpty;\r\n\r\npublic class CommentDTO {\r\n\r\n    @NotEmpty\r\n    @Length(max = 140)\r\n    private String text;\r\n\r\n    \/\/Methods are omitted.\r\n}<\/pre>\n
    Let\u2019s move on and find out how we can add validation to a REST API with Spring MVC 3.1.<\/p>\n
    Spring MVC 3.1 Is a Good Start<\/h2>\n
    We can add validation to our REST API by following these steps:<\/p>\n
      \n
    1. Implement a controller method and ensure that its input is validated.<\/li>\n
    2. Implement the logic which handles validation errors.<\/li>\n<\/ol>\n
      Both of the steps are described in the following subsections.<\/p>\n
      Implementing the Controller<\/h4>\n
      We can implement our controller by following these steps:<\/p>\n
        \n
      1. Create a class called CommentController<\/em> and annotate this class with the @Controller<\/em> annotation.<\/li>\n
      2. Add an add()<\/em> method to the CommentController<\/em> class which takes the added comment as a method parameter.<\/li>\n
      3. Annotate the method with @RequestMapping<\/em> and @ResponseBody annotations.<\/li>\n
      4. Apply the @Valid<\/em> and @RequestBody<\/em> annotations to the method parameter.<\/li>\n
      5. Return the added comment.<\/li>\n<\/ol>\n
        The source code of the CommentController<\/em> class looks as follows:<\/p>\n
        import org.springframework.beans.factory.annotation.Autowired;\r\nimport org.springframework.http.HttpStatus;\r\nimport org.springframework.stereotype.Controller;\r\nimport org.springframework.web.bind.annotation.*;\r\n\r\nimport javax.validation.Valid;\r\n\r\n@Controller\r\npublic class CommentController {\r\n\r\n    @RequestMapping(value = \"\/api\/comment\", method = RequestMethod.POST)\r\n    @ResponseBody\r\n    public CommentDTO add(@Valid @RequestBody CommentDTO comment) {\r\n        return comment;\r\n    }\r\n}<\/pre>\n
        We have now added a new method to our controller and added validation to it. When the validation fails, a MethodArgumentNotValidException<\/em> is thrown. Let\u2019s find out how we can return a meaningful response to the user of our API when the validation fails.<\/p>\n
        Handling Validation Errors<\/h4>\n
        We can implement the logic which handles the validation errors by following these steps:<\/p>\n
          \n
        1. Implement the data transfer objects which contains the information returned to the user of our REST API.<\/li>\n
        2. Implement the exception handler method.<\/li>\n<\/ol>\n
          These steps are described with more details in the following.<\/p>\n
          Creating the Data Transfer Objects<\/h2>\n
          First, we have to create the data transfer objects which contains the information returned to the user of our REST API. We can do this by following these steps:<\/p>\n
            \n
          1. Create a DTO which contains the information of a single validation error.<\/li>\n
          2. Create a DTO which wraps those validation errors together.<\/li>\n<\/ol>\n
            Let\u2019s get started.<\/p>\n
            The source code of the first DTO looks as follows:<\/p>\n
            public class FieldErrorDTO {\r\n\r\n    private String field;\r\n\r\n    private String message;\r\n\r\n    public FieldErrorDTO(String field, String message) {\r\n        this.field = field;\r\n        this.message = message;\r\n    }\r\n\r\n    \/\/Getters are omitted.\r\n}<\/pre>\n
            The implementation of the second DTO is rather simple. It contains a list of FieldErrorDTO<\/em> objects and a method which is used to add new field errors to the list. The source code of the ValidationErrorDTO<\/em> looks as follows:<\/p>\n
            import java.util.ArrayList;\r\nimport java.util.List;\r\n\r\npublic class ValidationErrorDTO {\r\n\r\n    private List<FieldErrorDTO> fieldErrors = new ArrayList<>();\r\n\r\n    public ValidationErrorDTO() {\r\n\r\n    }\r\n\r\n    public void addFieldError(String path, String message) {\r\n        FieldErrorDTO error = new FieldErrorDTO(path, message);\r\n        fieldErrors.add(error);\r\n    }\r\n\r\n    \/\/Getter is omitted.\r\n}<\/pre>\n
            The following listing provides an example Json document which is send back to the user of our API when the validation fails:
             
            <\/div> <\/div><\/p>\n
            {\r\n    \"fieldErrors\":[\r\n        {\r\n            \"field\":\"text\",\r\n            \"message\":\"error message\"\r\n        }\r\n    ]\r\n}<\/pre>\n
            Let\u2019s see how we can implement the exception handler method which creates a new ValidationErrorDTO<\/em> object and returns created object.<\/p>\n
            Implementing the Exception Handler Method<\/h2>\n
            We can add the exception handler method to our controller by following these steps:<\/p>\n
              \n
            1. Add a MessageSource<\/em> field to the CommentController<\/em> class. The message source is used to fetch localized error message for validation errors.<\/li>\n
            2. Inject the MessageSource<\/em> bean by using constructor injection.<\/li>\n
            3. Add a processValidationError()<\/em> method to the CommentController<\/em> class. This method returns ValidationErrorDTO<\/em> object and takes a MethodArgumentNotValidException<\/em> object as a method parameter.<\/li>\n
            4. Annotate the method with the @ExceptionHandler<\/em> annotation and ensure that the method is called when the MethodArgumentNotValidException<\/em> is thrown.<\/li>\n
            5. Annotate the method with the @ResponseStatus<\/em> annotation and ensure that the HTTP status code 400 (bad request) is returned.<\/li>\n
            6. Annotate the method with the @ResponseBody<\/em> annotation.<\/li>\n
            7. Implement the method.<\/li>\n<\/ol>\n
              Let\u2019s take a closer look at the implementation of the processValidationError()<\/em> method. We can implement this method by following these steps:<\/p>\n
                \n
              1. Get a list of FieldError<\/em> objects and process them.<\/li>\n
              2. Process the field errors one field error at the time.<\/li>\n
              3. Try to resolve a localized error message by using the MessageSource<\/em> object, current locale and the error code of the processed field error.<\/li>\n
              4. Return the resolved error message. If the error message is not found from the properties file, return the most accurate field error code.<\/li>\n
              5. Add a new field error by calling the addFieldError()<\/em> method of the ValidationErrorDTO<\/em> class. Pass the name of the field and the resolved error message as method parameters.<\/li>\n
              6. Return the created ValidationErrorDTO<\/em> object after each field error has been processed.<\/li>\n<\/ol>\n
                The source code of the CommentController class looks as follows:<\/p>\n
                import org.springframework.beans.factory.annotation.Autowired;\r\nimport org.springframework.context.MessageSource;\r\nimport org.springframework.context.i18n.LocaleContextHolder;\r\nimport org.springframework.http.HttpStatus;\r\nimport org.springframework.stereotype.Controller;\r\nimport org.springframework.validation.BindingResult;\r\nimport org.springframework.validation.FieldError;\r\nimport org.springframework.web.bind.MethodArgumentNotValidException;\r\nimport org.springframework.web.bind.annotation.*;\r\n\r\nimport javax.validation.Valid;\r\nimport java.util.List;\r\nimport java.util.Locale;\r\n\r\n@Controller\r\npublic class CommentController {\r\n\r\n    private MessageSource messageSource;\r\n\r\n    @Autowired\r\n    public CommentController(MessageSource messageSource) {\r\n        this.messageSource = messageSource;\r\n    }\r\n\r\n    \/\/The add() method is omitted.\r\n\r\n    @ExceptionHandler(MethodArgumentNotValidException.class)\r\n    @ResponseStatus(HttpStatus.BAD_REQUEST)\r\n    @ResponseBody\r\n    public ValidationErrorDTO processValidationError(MethodArgumentNotValidException ex) {\r\n        BindingResult result = ex.getBindingResult();\r\n        List<FieldError> fieldErrors = result.getFieldErrors();\r\n\r\n        return processFieldErrors(fieldErrors);\r\n    }\r\n\r\n    private ValidationErrorDTO processFieldErrors(List<FieldError> fieldErrors) {\r\n        ValidationErrorDTO dto = new ValidationErrorDTO();\r\n\r\n        for (FieldError fieldError: fieldErrors) {\r\n            String localizedErrorMessage = resolveLocalizedErrorMessage(fieldError);\r\n            dto.addFieldError(fieldError.getField(), localizedErrorMessage);\r\n        }\r\n\r\n        return dto;\r\n    }\r\n\r\n    private String resolveLocalizedErrorMessage(FieldError fieldError) {\r\n        Locale currentLocale =  LocaleContextHolder.getLocale();\r\n        String localizedErrorMessage = messageSource.getMessage(fieldError, currentLocale);\r\n\r\n        \/\/If the message was not found, return the most accurate field error code instead.\r\n        \/\/You can remove this check if you prefer to get the default error message.\r\n        if (localizedErrorMessage.equals(fieldError.getDefaultMessage())) {\r\n            String[] fieldErrorCodes = fieldError.getCodes();\r\n            localizedErrorMessage = fieldErrorCodes[0];\r\n        }\r\n\r\n        return localizedErrorMessage;\r\n    }\r\n}<\/pre>\n
                That is it. Let\u2019s spend a moment to evaluate what we have just done.<\/p>\n
                We Are Almost There<\/h4>\n
                We have now added validation to our REST API with Spring MVC 3.1. This implementation has one major benefit over the old approach:<\/p>\n
                We can trigger the validation process by using the @Valid<\/em> annotation.<\/p>\n
                However, the methods annotated with the @ExceptionHandler<\/em> annotation will be triggered only when the configured exception is thrown from the controller class which contains the exception handler method. This means that if our application has more than one controller, we have to create a common base class for our controllers and move the logic which handles the validation errors to that class. This might not sound like a big deal but we should prefer composition over inheritance<\/a>.<\/p>\n
                Spring MVC 3.2 provides the tools which we can use to remove the need of inheritance from our controllers. Let\u2019s move on and find out how this is done.<\/p>\n
                Spring MVC 3.2 to the Rescue<\/h2>\n
                Spring MVC 3.2 introduced a new @ControllerAdvice<\/em> annotation<\/a> which we can use to implement an exception handler component that processes the exceptions thrown by our controllers. We can implement this component by following these steps:<\/p>\n
                  \n
                1. Remove the logic which handles validation errors from the CommentController<\/em> class.<\/li>\n
                2. Create a new exception handler class and move the logic which processes validation errors to the created class.<\/li>\n<\/ol>\n
                  These steps are explained with more details in the following subsections.<\/p>\n
                  Removing Exception Handling Logic from Our Controller<\/h4>\n
                  We can remove the exception handling logic from our controller by following these steps:<\/p>\n
                    \n
                  1. Remove the MessageSource<\/em> field from the CommentController<\/em> class.<\/li>\n
                  2. Remove the constructor from our controller class.<\/li>\n
                  3. Remove the processValidationError()<\/em> method and the private methods from our controller class.<\/li>\n<\/ol>\n
                    The source code of the CommentController<\/em> class looks as follows:<\/p>\n
                    import org.springframework.stereotype.Controller;\r\nimport org.springframework.web.bind.annotation.*;\r\n\r\nimport javax.validation.Valid;\r\n\r\n@Controller\r\npublic class CommentController {\r\n\r\n    @RequestMapping(value = \"\/api\/comment\", method = RequestMethod.POST)\r\n    @ResponseBody\r\n    public CommentDTO add(@Valid @RequestBody CommentDTO comment) {\r\n        return comment;\r\n    }\r\n}<\/pre>\n
                    Our is next step is to create the exception handler component. Let\u2019s see how this is done.<\/p>\n
                    Creating the Exception Handler Component<\/h4>\n
                    We can create the exception handler component by following these steps:<\/p>\n
                      \n
                    1. Create a class called RestErrorHandler<\/em> and annotate it with the @ControllerAdvice<\/em> annotation.<\/li>\n
                    2. Add a MessageSource<\/em> field to the RestErrorHandler<\/em> class.<\/li>\n
                    3. Inject the MessageSource<\/em> bean by using constructor injection.<\/li>\n
                    4. Add the processValidationError()<\/em> method and the required private methods to the RestErrorHandler<\/em> class.<\/li>\n<\/ol>\n
                      The source code of the RestErrorHandler class looks as follows:<\/p>\n
                      import org.springframework.beans.factory.annotation.Autowired;\r\nimport org.springframework.context.MessageSource;\r\nimport org.springframework.context.i18n.LocaleContextHolder;\r\nimport org.springframework.http.HttpStatus;\r\nimport org.springframework.validation.BindingResult;\r\nimport org.springframework.validation.FieldError;\r\nimport org.springframework.web.bind.MethodArgumentNotValidException;\r\nimport org.springframework.web.bind.annotation.ControllerAdvice;\r\nimport org.springframework.web.bind.annotation.ExceptionHandler;\r\nimport org.springframework.web.bind.annotation.ResponseBody;\r\nimport org.springframework.web.bind.annotation.ResponseStatus;\r\n\r\nimport java.util.List;\r\nimport java.util.Locale;\r\n\r\n@ControllerAdvice\r\npublic class RestErrorHandler {\r\n\r\n    private MessageSource messageSource;\r\n\r\n    @Autowired\r\n    public RestErrorHandler(MessageSource messageSource) {\r\n        this.messageSource = messageSource;\r\n    }\r\n\r\n    @ExceptionHandler(MethodArgumentNotValidException.class)\r\n    @ResponseStatus(HttpStatus.BAD_REQUEST)\r\n    @ResponseBody\r\n    public ValidationErrorDTO processValidationError(MethodArgumentNotValidException ex) {\r\n        BindingResult result = ex.getBindingResult();\r\n        List<FieldError> fieldErrors = result.getFieldErrors();\r\n\r\n        return processFieldErrors(fieldErrors);\r\n    }\r\n\r\n    private ValidationErrorDTO processFieldErrors(List<FieldError> fieldErrors) {\r\n        ValidationErrorDTO dto = new ValidationErrorDTO();\r\n\r\n        for (FieldError fieldError: fieldErrors) {\r\n            String localizedErrorMessage = resolveLocalizedErrorMessage(fieldError);\r\n            dto.addFieldError(fieldError.getField(), localizedErrorMessage);\r\n        }\r\n\r\n        return dto;\r\n    }\r\n\r\n    private String resolveLocalizedErrorMessage(FieldError fieldError) {\r\n        Locale currentLocale =  LocaleContextHolder.getLocale();\r\n        String localizedErrorMessage = messageSource.getMessage(fieldError, currentLocale);\r\n\r\n        \/\/If the message was not found, return the most accurate field error code instead.\r\n        \/\/You can remove this check if you prefer to get the default error message.\r\n        if (localizedErrorMessage.equals(fieldError.getDefaultMessage())) {\r\n            String[] fieldErrorCodes = fieldError.getCodes();\r\n            localizedErrorMessage = fieldErrorCodes[0];\r\n        }\r\n\r\n        return localizedErrorMessage;\r\n    }\r\n}<\/pre>\n
                      We Are Finally There<\/h4>\n
                      Thanks to Spring MVC 3.2, we have now implemented an elegant solution where the validation is triggered by the @Valid<\/em> annotation, and the exception handling logic is moved to a separate class. I think that we can call it a day and enjoy the results of our work.<\/p>\n
                      Summary<\/h2>\n
                      This blog post has taught us that<\/p>\n