Koto.Api.FastEndpoints

FastEndpoints integration for Koto DDD building blocks.

What's included

Failed results are rendered by KotoProblemDetails from Koto.Api.AspNetCore — all Result.Errors are sent (multiple errors become RFC 7807 validation problem details grouped by Error.Field), with errorCode/errorCodes and correlationId extensions.

Setup

// Program.cs
builder.Services.AddKotoApi();          // includes AddKotoAspNetCore()
// Or customize the Error.Code → HTTP status registry:
builder.Services.AddKotoApi(o => o.Map("payments.gateway-failed", 502));
builder.Services.AddFastEndpoints();
// ... other services

var app = builder.Build();
app.UseKotoApi(); // CorrelationId middleware + exception handler
app.UseFastEndpoints();
app.Run();

Implementing an endpoint

// Void command (204 on success)
public class DeleteOrderEndpoint : CommandEndpoint<DeleteOrderCommand>
{
    public override void Configure()
    {
        Delete("/orders/{id}");
        AllowAnonymous();
    }

    public override async Task HandleAsync(DeleteOrderCommand req, CancellationToken ct)
        => await SendCommandAsync(req, ct);
}

// Command with result (200 on success)
public class PlaceOrderEndpoint : CommandEndpoint<PlaceOrderCommand, OrderId>
{
    public override void Configure()
    {
        Post("/orders");
        AllowAnonymous();
    }

    public override async Task HandleAsync(PlaceOrderCommand req, CancellationToken ct)
        => await SendCommandAsync(req, ct);
}

// Query (GET, 200/404)
public class GetOrderEndpoint : QueryEndpoint<GetOrderQuery, OrderDto>
{
    public override void Configure()
    {
        Get("/orders/{id}");
        AllowAnonymous();
    }

    public override async Task HandleAsync(GetOrderQuery req, CancellationToken ct)
        => await SendQueryAsync(req, ct);
}

Server-derived fields (claims, route, tenant)

When a command/query carries fields that must come from the server (the caller's user id, tenant, correlation id) and must not be bindable from the request body, use the mapped endpoints. The request DTO omits those fields; ToCommand/ToQuery builds the command from the request and the endpoint context (User, Route<T>(), headers):

public sealed record SubmitJudgmentRequest(Guid SubmissionId, int GoeScore); // no JudgeId on the wire
public sealed record SubmitJudgmentCommand(Guid JudgeId, Guid SubmissionId, int GoeScore) : ICommand<Judgment>;

public sealed class SubmitJudgmentEndpoint
    : MappedCommandEndpoint<SubmitJudgmentRequest, SubmitJudgmentCommand, Judgment>
{
    public override void Configure() { Post("/api/v1/judgments"); Policies("IsJudge"); }

    protected override SubmitJudgmentCommand ToCommand(SubmitJudgmentRequest r) =>
        new(JudgeId: User.GetUserId(), r.SubmissionId, r.GoeScore); // JudgeId from claims, not the body
}

Prefer the plain CommandEndpoint/QueryEndpoint when the request is the command (no server-derived fields). HandleAsync is sealed on the mapped variants — you only implement Configure and ToCommand/ToQuery.

Error code → HTTP status mapping

Status codes come from KotoHttpErrorOptions (Koto.Api.AspNetCore) — an extensible registry (exact code → custom rules → suffix → prefix → fallback). Defaults:

Customize via AddKotoApi(o => o.Map("subscription.payment-failed", 502)).