A structured programming model for ASP.NET Core Minimal APIs.

An endpoint

That is the whole file.

The attribute declares the route. The namespace supplies the operation id (InvoicesGet), so nothing has to be named twice. The request record is bound from the route, and the response is serialized and documented.

namespace Billing.Endpoints.Invoices.Get;

public sealed record GetInvoice(string InvoiceId);

[Get("invoices/{invoiceId}")]
public sealed class Endpoint(IInvoiceStore store) : ApiEndpoint<GetInvoice, InvoiceView>
{
    public override async Task<InvoiceView> HandleAsync(GetInvoice request, CancellationToken ct) =>
        InvoiceView.From(await store.GetAsync(request.InvoiceId, ct));
}

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddNativeEndpoints();

var app = builder.Build();
app.MapEndpointGroup().MapEndpointsFrom(typeof(Program).Assembly, routePrefix: "/api");
app.Run();

Why

Minimal APIs are a good runtime and an awkward organizing principle.

Past a few dozen routes you are choosing between a Program.cs nobody wants to open, a pile of extension methods that hide the route table, or a framework that replaces ASP.NET Core with its own parallel universe. NativeEndpoints takes the middle path: it gives you a place to put an endpoint and takes nothing away.

Base types

Five shapes, and a handler that decides.

ApiEndpointWithResult covers operations whose status depends on what happened. The documented schema stays the response type; the wrapper never reaches the wire.

public override async Task<EndpointResult<InvoiceView>> HandleAsync(
    CreateInvoice cmd, CancellationToken ct)
{
    var (invoice, created) = await store.UpsertAsync(cmd, ct);
    return created
        ? EndpointResult.Status(StatusCodes.Status201Created, InvoiceView.From(invoice))
        : EndpointResult.Ok(InvoiceView.From(invoice));
}

Binding

Route, then body, then query.

Route wins over the body so a resource identifier in the URL cannot be contradicted by the payload. Built in: string, bool, int, long, Guid, enum, DateTimeOffset, anything implementing IParsable<T>, arrays and lists of those from the query string, plus headers and claims.

NE0004: Contract 'Transfer' has parameter 'amount' of unsupported type 'Money'.
        Register a value binder or use a supported type.

Errors

Mapping is domain knowledge, so it lives with the domain.

Domain exceptions become responses through translators you register, rather than a global filter every part of the application has to agree on. Problems are written as RFC 9457 ProblemDetails through IProblemDetailsService.

public sealed class BillingExceptionTranslator : IEndpointExceptionTranslator
{
    public EndpointProblem? Translate(Exception exception) => exception switch
    {
        InvoiceNotFoundException  => EndpointProblem.General(404, "Invoice not found"),
        InvoiceLockedException e  => EndpointProblem.General(409, e.Message),
        _ => null
    };
}

Unload safety

And it unloads.

If you host plugins in collectible AssemblyLoadContexts, endpoint frameworks are usually where unloading goes to die. Process-global registries, static configuration and captured handler MethodInfo all root the assembly you are trying to release — and none of it is visible until you measure.

[Fact]
public async Task Module_unloads()
{
    var evidence = await CollectibleEndpointFixture.RunCyclesAsync(cycles: 3);
    UnloadEvidence.Verify(evidence, gcRounds: 32);
}

Compared to FastEndpoints

Choose this when you want the endpoint-class shape and nothing else.

FastEndpoints is a mature, popular and genuinely good library, and it does considerably more than this one. If you want a batteries-included framework, use it.

What it does not do

The narrow parts, stated plainly.

Documentation

Read the manual.