Skip to content

Latest commit

 

History

History
152 lines (104 loc) · 5.72 KB

index.adoc

File metadata and controls

152 lines (104 loc) · 5.72 KB

Vert.x Web Validation

Table of Contents

Vert.x Web Validation helps you parse and validate parameters and bodies of the incoming requests.

You can:

  • Parse and validate request parameters, serialized and exploded too

  • Parse and validate request bodies, including json and forms

  • Configure request predicates

  • Allow different bodies in the same route and consistently parse and validate it

  • Define custom rules to parse and validate

  • Manage the parsing and validation failures

It uses Vert.x Json Schema to define schemas of your request parameters/bodies.

Using Vert.x Web Validation

To use Vert.x Web Validation, add the following dependency to the dependencies section of your build descriptor:

  • Maven (in your pom.xml):

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-web-validation</artifactId>
  <version>${maven.version}</version>
</dependency>

  • Gradle (in your build.gradle file):

dependencies {
  compile 'io.vertx:vertx-web-validation:${maven.version}'
}

Without Vert.x Web Validation

When you receive an HTTP request, you usually need to perform parsing and validation of parameters and body of the request:

{@link examples.WebValidationExamples#withoutWebValidation}

Vert.x Web Validation provides an easy to use API to build an handler that performs parsing and validation of the request:

{@link examples.WebValidationExamples#withWebValidation}

Creating the ValidationHandler

This module provides an easy to use builder API to create your {@link io.vertx.ext.web.validation.ValidationHandler}, the {@link io.vertx.core.Handler} that performs the parsing and validation of the request. To create this builder use {@link io.vertx.ext.web.validation.builder.ValidationHandlerBuilder#create(SchemaRepository)}.

Defining parameters

You can define parameters located in four different locations of your request: query, cookie, header, path.

Every parameter is represented by a {@link io.vertx.ext.web.validation.impl.parameter.ParameterProcessor}, that you can easily create with methods provided in {@link io.vertx.ext.web.validation.builder.Parameters}:

{@link examples.WebValidationExamples#parameters}

Note that all these methods requires a schema that validator can use to perform the validation. The schema is also used to infer the correct parser

While header and path parameters allows only simple parameters, query and cookie allows complex parameters like exploded and deep object:

{@link examples.WebValidationExamples#parametersComplex}

For more info on all available parameters, look at {@link io.vertx.ext.web.validation.builder.Parameters} documentation.

Defining request bodies

Every body type is represented by a {@link io.vertx.ext.web.validation.impl.parameter.ParameterProcessor} and matches with request body using Content-type header. You can define one or multiple bodies that the ValidationHandler should manage. If no matching body processor is found, the validation won’t fail unless you specified the body required predicate explained below

You can easily create these processor with methods provided in {@link io.vertx.ext.web.validation.builder.Bodies}:

{@link examples.WebValidationExamples#bodies}

In this example the ValidationHandler will be able to manage two different body types that consistently parse and validate. In particular the form body will be converted to a json object. When you retrieve the parsed result, you don’t need to care if the request body was a form or a json

For more info on all available body processors, look at {@link io.vertx.ext.web.validation.builder.Bodies} documentation.

Defining request predicates

You can define request predicates in ValidationHandler with {@link io.vertx.ext.web.validation.RequestPredicate}. For example, to define a "request body required" predicate:

{@link examples.WebValidationExamples#requestBodyRequired}

Building the ValidationHandler

After you configured all parameters, bodies and request predicates, you can build the ValidationHandler:

{@link examples.WebValidationExamples#buildAndMount}

Using the parsed parameters and body

The ValidationHandler will place the parsed values into {@link io.vertx.ext.web.RoutingContext}:

{@link examples.WebValidationExamples#useParameters}

Manage the failures

Every time a ValidationHandler encounters both a parsing or a validation failure, it fails the RoutingContext with 400 status code and an instance of a subclass of {@link io.vertx.ext.web.validation.BadRequestException} as cause. To learn how to manage failures, look at Vert.x Web doc and {@link io.vertx.ext.web.Router#errorHandler(int,Handler)} method.

The possible subclasses of {@link io.vertx.ext.web.validation.BadRequestException} are:

  • {@link io.vertx.ext.web.validation.ParameterProcessorException}: To manage a parameter failure

  • {@link io.vertx.ext.web.validation.BodyProcessorException}: To manage a body failure

  • {@link io.vertx.ext.web.validation.RequestPredicateException}: To manage a request predicate failure

For example:

{@link examples.WebValidationExamples#manageFailure}

BadRequestException also provides an handy method called {@link io.vertx.ext.web.validation.BadRequestException#toJson()} that converts the exception to a Json

Note that the ValidationHandler is designed as fail-fast, so as soon as an error is encountered, the ValidationHandler will fail the RoutingContext