Model Binding

Every value in an HTTP request is text. The path is text, the query string is text, the body is a stream of bytes. Model binding is the step that turns that into the typed arguments your handler declares.

It runs before your code. By the time the first line of your method executes, binding has already succeeded. If it could not succeed, the request has already been answered with a 400 and your method was never called.

Knowing that changes how you debug. A 400 you cannot find in your own code is usually binding, and looking for it in your validation rules is looking one step too late.

[ApiController]
[Route("api/employees")]
public sealed class EmployeesController(EmployeeService employees) : ControllerBase
{
    // GET /api/employees/search?department=FIN&page=2&pageSize=50
    [HttpGet("search")]
    public Task<IReadOnlyList<Employee>> Search([FromQuery] EmployeeSearch search) =>
        employees.SearchAsync(search);

    // POST /api/employees/482/absences
    [HttpPost("{id:int}/absences")]
    public async Task<ActionResult<AbsenceResponse>> AddAbsence(
        int id,
        [FromBody] CreateAbsenceRequest request,
        [FromHeader(Name = "X-Request-Id")] string? requestId,
        CancellationToken ct)
    {
        var absence = await employees.AddAbsenceAsync(id, request, requestId, ct);

        return Ok(AbsenceResponse.From(absence));
    }
}

public sealed class EmployeeSearch
{
    public string? Department { get; set; }
    public int Page { get; set; } = 1;
    public int PageSize { get; set; } = 25;
}

• FromQuery on a complex type binds each of its properties from the query string by name. One parameter instead of five, and the defaults live on the class where they can be read.
• id carries no attribute and is a simple type, so binding finds it in the route values, which is where the template put it.
• FromBody states that this parameter is the payload. The inference would have reached the same conclusion here, so writing it is a choice: explicit intent at the cost of a little noise.
• FromHeader with an explicit name handles headers whose names are not valid C# identifiers. The nullable type says the header is optional — a non-nullable string would be treated as required and produce a 400 when the caller omits it.
• CancellationToken is not bound from any part of the message. It comes from the request's abort signal, so it is cancelled if the caller disconnects.
• Nothing in this method checks whether id is a number or whether the body parsed. Those questions were answered before it was called.

POST /api/employees/482/absences HTTP/1.1
Content-Type: application/json

{ "startDate": "not-a-date", "days": 2 }

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "$.startDate": [
      "The JSON value could not be converted to System.DateOnly."
    ]
  }
}

• The status is 400 because the caller sent something that cannot become the declared type. Nothing failed in your code, so 500 would be wrong.
• The content type is application/problem+json, a standard shape for error bodies. Callers can read it the same way for every endpoint in the API.
• The key is a path into the JSON document rather than a property name, because the failure happened while reading the document.
• Only one error is reported. JSON deserialization stops at the first value it cannot convert, so fixing that one can reveal the next. Values bound from the route and query string are all checked, so those failures are reported together.
• This response was produced by the ApiController convention. Without that attribute, the failure would sit in model state and your action would run with a partially bound object, which is a considerably worse default.