The endpoint should not own the whole feature
ASP.NET Core Minimal APIs make it easy to define routes close to app startup. That is useful for small services, but the convenience becomes a maintenance problem when every route handler starts doing validation, mapping, database queries, logging, and business decisions.
A maintainable API boundary keeps the endpoint thin: bind HTTP input, call a named workflow, and return a typed result. Contracts, services, and persistence rules should be visible enough that another developer can change one layer without opening every file.
app.MapPost("/invoices", async (
CreateInvoiceRequest request,
IInvoiceService invoices,
CancellationToken ct
) => Results.Created("/invoices", await invoices.CreateAsync(request, ct)));Separate request contracts from database models
Public API contracts are promises to clients. Database models are persistence details. They often look similar at first, but they change for different reasons.
Use request and response records to control what enters and leaves the API. This gives you a stable place to document validation rules, defaults, and versioning decisions.
Try the idea
API boundary map
Click a layer to see what it should own.
Accept HTTP input, bind route/body data, return a typed response.
app.MapPost("/invoices", CreateInvoice)Validation belongs before side effects
Validation should happen before writes, external calls, or queued jobs. Return errors in a consistent shape so frontend forms can map field errors, summary errors, and retryable failures without guessing.
Production notes for .NET APIs
Backend code becomes maintainable when HTTP boundaries, service boundaries, and persistence boundaries are named. A route that works once is not the same as an API that another developer can safely extend.
Before shipping, review lifetimes, validation behavior, request contracts, logging, and the exact error shape that frontend code will receive.
Conclusion
Minimal APIs stay maintainable when you keep the endpoint minimal and give the real workflow a clear home.