Routing

Routing answers one question: which piece of my code should handle this request? It happens in two stages. The routing middleware compares the request against every registered route template and records the endpoint it chose. Later, at the end of the pipeline, the endpoint middleware runs that endpoint.

The gap between those two stages is useful rather than incidental. Middleware registered between them can see which endpoint was selected and read the metadata attached to it, which is how per-endpoint authorization and CORS policies work at all.

Both URL segments and the HTTP method take part in matching. GET and POST on the same path are two different endpoints.

[ApiController]
[Route("api/employees")]
public sealed class EmployeesController(EmployeeService employees) : ControllerBase
{
    // GET /api/employees?page=2
    [HttpGet]
    public Task<IReadOnlyList<Employee>> List([FromQuery] int page = 1) =>
        employees.ListAsync(page);

    // GET /api/employees/482
    [HttpGet("{id:int}")]
    public Task<Employee?> GetById(int id) => employees.FindAsync(id);

    // GET /api/employees/by-code/FIN
    [HttpGet("by-code/{code:alpha:length(3)}")]
    public Task<IReadOnlyList<Employee>> ByDepartmentCode(string code) =>
        employees.ListByDepartmentAsync(code);

    // GET /api/employees/482/absences/2024
    [HttpGet("{id:int}/absences/{year:int:range(2000,2100)}")]
    public Task<IReadOnlyList<Absence>> Absences(int id, int year) =>
        employees.ListAbsencesAsync(id, year);

    // GET /api/employees/me
    [HttpGet("me")]
    public Task<Employee?> Current() => employees.FindCurrentAsync(User);
}

• The Route attribute on the class sets a prefix, and each method's template is appended to it. Change the prefix once and every endpoint in the class moves.
• A segment in braces is a route parameter. Its name has to match the method parameter, and the value arrives converted to that parameter's type.
• A colon inside the braces adds a constraint. The template with id:int only matches when that segment is an integer, so a request for /api/employees/abc does not match this endpoint at all, rather than matching and failing later.
• Constraints can be chained. The code:alpha:length(3) template requires three letters, so FIN matches and F1 does not.
• The literal segment me sits alongside the id:int template without conflict, because a literal is more specific than a parameter and wins when both could match.
• These actions return their values directly to keep the focus on templates. The next lesson covers returning status codes properly, which is what real endpoints do.