Request Validation

Validation at the boundary means a request is checked as it arrives, before any business logic runs. Everything past that point can then assume the data is shaped correctly, which removes a layer of defensive checking from the rest of the code.

The alternative is validation scattered through the layers: a null check in the service, a length check in the repository, a constraint in the database that surfaces as a 500. The same rule ends up expressed three times, in three places, with three different messages, and a caller cannot predict which one they will hit.

The split matters because the two kinds fail differently. A field rule fails the same way every time and can be described in the API documentation: fullName is required, maximum 200 characters. A business rule depends on the state of the system, so the same request can be valid on Monday and invalid on Tuesday.

Run field rules first. There is no point querying the database to check a department when the department id is missing, and doing so turns a clean 400 into a confusing one.

public sealed record CreateEmployeeRequest(
    [Required, StringLength(200)] string FullName,
    [Required, EmailAddress] string Email,
    [Range(1, int.MaxValue)] int DepartmentId,
    DateOnly StartDate);

app.MapPost("/api/employees", async (
    CreateEmployeeRequest request, AppDbContext db, CancellationToken ct) =>
{
    var errors = new Dictionary<string, string[]>();

    var department = await db.Departments
        .SingleOrDefaultAsync(d => d.Id == request.DepartmentId, ct);

    if (department is null)
    {
        errors["departmentId"] = ["No department exists with that id."];
    }
    else if (request.StartDate < department.OpenedOn)
    {
        errors["startDate"] = ["Start date cannot be before the department opened."];
    }

    if (await db.Employees.AnyAsync(e => e.Email == request.Email, ct))
    {
        errors["email"] = ["An employee already exists with that email address."];
    }

    if (errors.Count > 0)
    {
        return Results.ValidationProblem(errors);
    }

    var created = await db.AddEmployeeAsync(request, ct);
    return Results.Created($"/api/employees/{created.Id}", created);
});

• The attributes on the record describe field rules in the one place a reader looks for them. They also feed the generated API documentation, so the rules reach callers rather than living only in your head. Note that attributes alone do not run in a minimal API — you need a validation step, either the framework's or a small filter of your own.
• The handler collects errors in a dictionary rather than returning on the first failure, so a caller fixing a form sees every problem at once instead of discovering them one request at a time.
• The department check and the start-date check are business rules: both need a row from the database. Neither could be expressed as an attribute, because an attribute knows nothing about departments.
• Results.ValidationProblem returns 400 with a standard problem document containing the field errors, keyed by field name. Those keys are what let a client attach each message to the right input.
• The duplicate email check returns a field error here. Returning 409 Conflict instead is equally defensible — what matters is choosing one and applying it across every endpoint that can produce a duplicate.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "departmentId": ["No department exists with that id."],
    "email": ["An employee already exists with that email address."]
  }
}

• The errors object is keyed by field, so a form can highlight departmentId and email without parsing prose.
• Each value is an array, because one field can fail more than one rule.
• Both failures are reported together. A response containing only the first would send the caller round the loop twice for a problem you already knew about.
• The message says what is wrong in terms the caller can act on. It does not mention tables, constraints or exception types.