Minimal APIs (.NET 10)

Core Principles

1. Minimal APIs are the default — Use controllers only when migrating legacy code. Minimal APIs are lighter, faster, and compose well with any architecture style.
2. Group endpoints with MapGroup — Never scatter individual MapGet/MapPost calls in Program.cs. Group related endpoints together.
3. Use TypedResults for OpenAPI — TypedResults.Ok(value) gives you compile-time type safety AND correct OpenAPI documentation. Results.Ok(value) does not.
4. Metadata over comments — Use .WithName(), .WithTags(), .WithSummary() to document endpoints. The metadata feeds into OpenAPI specs.

Patterns

Endpoint Group Auto-Discovery (Required Pattern)

Every endpoint group lives in its own file and implements IEndpointGroup. A single app.MapEndpoints() call in Program.cs discovers and registers all groups automatically. Program.cs never changes when you add new endpoint groups.