• Nerdigy
  • \
  • Validating Minimal APIs

frontmatter.coverAlt

Validating Minimal APIs

Minimal APIs in ASP.NET Core provide a lightweight approach to building web services, but this simplicity comes with trade-offs. For example, minimal APIs don’t automatically validate requests using data annotations on request models.

In this post, we’ll explore how to implement data annotation validation in minimal APIs, when using libraries like Fluent Validations might make sense, and how we can opt-int to validation mechanisms via endpoint filters.

🛑 Problem

Consider the following request model:

public sealed record LoginRequest
{
    [EmailAddress]
    public string Email { get; set; } = string.Empty;
    [MinLength(8)]
    public string Password { get; set; } = string.Empty;
}

And an endpoint in a minimal API:

public static void MapEndpoint(IEndpointRouteBuilder app)
{
    app.MapPost("/login", (LoginRequest request) => {
        // Do something with the request
    });
}

Because we’re using minimal APIs, ASP.NET does not automatically validate this model. If a client sends an invalid email or a short password, the request will proceed without any validation errors. The data annotation attributes are ignored. Minimal APIs are “minimal” after all with an “opt in” philosophy.

🔢 Validating Data Annotations

Since we no longer have middleware to validate data annotations for us, we have to handle validation ourselves. We can validate data annotations on a request using the Validator.cs class from the System.ComponentModel.DataAnnotations namespace:

public static void MapEndpoint(IEndpointRouteBuilder app)
{
    app.MapPost("/login", (LoginRequest request) => {
        var validationResults = new List<ValidationResult>();
        var validationContext = new ValidationContext(request);

        if (!Validator.TryValidateObject(request, validationContext, validationResults, true))
        {
            var errors = validationResults.ToDictionary(
                v => v.MemberNames.FirstOrDefault() ?? "Error",
                v => new[] { v.ErrorMessage! }
            );
            
            return Results.ValidationProblem(errors);
        }

        // Do something with the request
    });
}

Under the covers Validator.TryValidateObject uses reflection to call each annotated property’s validation logic and populates the validationResults list with any errors.

We now have a basic validation mechanism in place. If the request model is invalid, the client will receive a 400 Bad Request response with the validation errors. If we want to use this code in multiple endpoints we can abstract this logic into a reusable endpoint filter:

public sealed class ValidationFilter<T> : IEndpointFilter
    where T : class
{
    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context, 
        EndpointFilterDelegate next)
    {
        if (context.Arguments.FirstOrDefault(x => x is T) as T is not { } request)
        {
            return TypedResults.BadRequest();
        }
        
        var results = new List<ValidationResult>();

        if (!Validator.TryValidateObject(request, new ValidationContext(request), results, true))
        {
            var errors = results.ToDictionary(
                v => v.MemberNames.FirstOrDefault() ?? "Error",
                v => new[] { v.ErrorMessage! }
            );
            
            return Results.ValidationProblem(errors);
        }

        return await next(context);
    }
}

And now we can apply our validation filter to any minimal API endpoint needing validation:

public static void MapLoginEndpoint(this IEndpointRouteBuilder app)
{
    app.MapPost("/login", (LoginRequest request) =>
    {
        // Do something with the request
    }).AddEndpointFilter<ValidationFilter<Request>>();
}

To make our code even more concise we can add an extension method to the RouteHandlerBuilder class:

public static class ValidationFilterExtensions
{
    public static RouteHandlerBuilder ValidateRequest<T>(this RouteHandlerBuilder builder) 
        where T : class
    {
        return builder.AddEndpointFilter<ValidationFilter<T>>();
    }
}

And our endpoint definition becomes even easier to read:

public static void MapLoginEndpoint(this IEndpointRouteBuilder app)
{
    app.MapPost("/login", (LoginRequest request) =>
    {
        // Do something with the request
    }).ValidateRequest<LoginRequest>();
}

We now have a simple and reusable way to execute simple validation in our minimal APIs. If you were curious how this was originally done in .NET with controllers and middleware, check out the DataAnnotationsModelValidator.cs class.

⚠️ Limitations

While data annotations are a simple and effective way to validate request models, they have some limitations:

  • ❌ Reflection Overhead: The Validator.TryValidateObject method uses reflection to validate the request model. This can be slow for complex models or large collections.
  • ❌ Single Error Per Property: The Validator.TryValidateObject method only returns the first error for each property. If you need to return all errors for a property, you’ll need to implement your own validation logic.
  • ❌ No Custom Validation Logic: Data annotations are limited to built-in validation attributes. If you need custom validation logic, you’ll need to implement it yourself.

🆚 Alternatives

FluentValidation is a great choice for scenarios that require more flexibility, complex validation logic, or dynamic validation. Here are some situations where FluentValidation might make more sense:

✅ Complex Validation Logic: FluentValidation allows you to define complex validation rules using a fluent API.

# A model validates that the down payment is at least 20% of the loan amount, 
# unless a special exception is granted.
RuleFor(x => x.DownPayment)
    .GreaterThanOrEqualTo(x => x.LoanAmount * 0.2)
    .When(x => x.SpecialException == false)
    .WithMessage("DownPayment must be at least 20% of LoanAmount.");

✅ Dynamic Validation: FluentValidation allows you to define validation rules based on the state of the model.

# A model validates that manager approval is required for loans above $50,000.
RuleFor(x => x.ManagerApproval)
    .NotNull()
    .When(x => x.LoanAmount > 50000)
    .WithMessage("Manager approval is required for loans above $50,000.");

✅ Reusable Validation Logic: FluentValidation allows you to define reusable validation rules that can be shared across multiple models.

# A validator for the Address model that validates the street and zip code.
public class AddressValidator : AbstractValidator<Address>
{
    public AddressValidator()
    {
        RuleFor(a => a.Street).NotEmpty();
        RuleFor(a => a.ZipCode).Matches(@"^\d{5}$").WithMessage("Invalid zip code.");
    }
}
# A validator for the User model that validates the address using the AddressValidator.
public class UserValidator : AbstractValidator<User>
{
    public UserValidator()
    {
        RuleFor(x => x.Address).SetValidator(new AddressValidator());
    }
}

Fluent Validations

To use Fluent Validations in minimal APIs, we will want to make a few modifications.

1️⃣ First we’ll want to install the FluentValidation packages:

dotnet add package FluentValidation
dotnet add package FluentValidation.AspNetCore

2️⃣ Next we’ll create a validator for our LoginRequest model:

public sealed class LoginRequestValidator : AbstractValidator<LoginRequest>
{
    public LoginRequestValidator()
    {
        RuleFor(x => x.Email).NotEmpty().EmailAddress();
        RuleFor(x => x.Password).NotEmpty().MinimumLength(8);
    }
}

Note: We can remove the data annotations from the LoginRequest model since we’re using Fluent Validations.

3️⃣ We’ll want to register our validators with the service collection:

builder.Services.AddValidatorsFromAssembly(Assembly.GetExecutingAssembly());

4️⃣ Finally, we’ll update our validation filter to use Fluent Validations:

public sealed class ValidationFilter<T> : IEndpointFilter
{
    private readonly IEnumerable<IValidator<T>> _validators;

    public ValidationFilter(IEnumerable<IValidator<T>> validators)
    {
        _validators = validators;
    }

    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context, 
        EndpointFilterDelegate next)
    {
        if (context.Arguments.FirstOrDefault(x => x.GetType() == typeof(T)) is not T request)
            return TypedResults.BadRequest();
        
        var cancellationToken = context.HttpContext.RequestAborted;
        var validations = _validators.Select(x => x.ValidateAsync(request, cancellationToken));
        
        var results = await Task.WhenAll(validations);
        var failures = results.SelectMany(x => x.Errors).ToList();
        
        if (failures.Count > 0)
            return TypedResults.ValidationProblem(new ValidationResult(failures).ToDictionary());

        return await next(context);
    }
}

Our validation filter now uses the Fluent Validation library to validate the request model.

✨ Conclusion

Minimal APIs provide great flexibility but don’t automatically enforce data annotation validation. By implementing a reusable validation filter and an extension method, we can keep our endpoints clean, maintainable, and free from repetitive validation logic. For scenarios that require more complex validation logic, FluentValidation is a great alternative that provides a fluent API for defining validation rules. Until next time, stay curious! 🚀