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.AddMinimalEndpoints();

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. MinimalEndpoints 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 — and you can register your own parser.

builder.Services.AddMinimalEndpoints(o => o.ValueBinders.Add<Money>(Money.TryParse));

NE0002: Contract 'Transfer' has parameter 'amount' of unsupported type 'Money'.
        Implement IParsable<Money>, or register a parser with
        AddMinimalEndpoints(o => o.ValueBinders.Add<Money>(...)).

Native AOT

Supported, and checked on every push.

The source generator ships inside the MinimalEndpoints package as an analyzer. dotnet add package MinimalEndpoints brings it along. Nothing to configure.

using MinimalEndpoints.Generated;

app.MapEndpointGroup().Map(routePrefix: "/api");

var builder = WebApplication.CreateSlimBuilder(args);
builder.Services.AddMinimalEndpoints();

var app = builder.Build();

// A source-generated serializer context: the JSON half of the AOT story.
app.MapEndpointGroup("Aot", AotJson.Default).Map(routePrefix: "/api");
app.Run();

[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
[JsonSerializable(typeof(GetWidget))]
[JsonSerializable(typeof(WidgetView))]
internal partial class AotJson : JsonSerializerContext;

Performance

At minimal-API parity, and measured.

The per-request pipeline resolves serializer metadata once per endpoint, memoizes a binding plan per contract, streams request bodies in one pass where it provably can, and does O(1) route and query lookups. The repository carries a BenchmarkDotNet suite so the claim is checkable rather than aspirational.

Diagnostics

What the build tells you.

[assembly: EndpointValueBinder(typeof(Money))]

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 void Endpoint_assemblies_are_collected()
{
    var evidence = CollectibleEndpointFixture.RunCycles(cycles: 3);
    UnloadEvidence.AssertAllCollected(evidence);
}

Packages

Three packages, and what each one drags in.

builder.Services.AddOpenApi();
builder.Services.AddMinimalEndpointsOpenApi();

Samples

Three of them, in the repository.

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.