Minimal APIC#

Integração com Minimal API

A Minimal API usa o mesmo pipeline HTTP do ASP.NET Core, então reutiliza exatamente o mesmo `ImmutableLogMiddleware`. A diferença está no registro funcional no `Program.cs` e em como você define evento e trilha por endpoint via `HttpContext.Items`.

Reaproveite o middleware

O código do middleware é idêntico ao da página ASP.NET Core — copie o `ImmutableLogMiddleware.cs` de lá. Aqui mostramos apenas o registro e o uso em endpoints Minimal API.

→ Ver o código completo do ImmutableLogMiddleware (ASP.NET Core)

Registro no Program.cs

Registre as opções, o `IHttpClientFactory` e o middleware. A ordem importa: chame `UseMiddleware` antes de mapear os endpoints.

csharp

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient("immutablelog", c => c.Timeout = TimeSpan.FromSeconds(5));
builder.Services.AddSingleton(new ImmutableLogOptions
{
    ApiKey = Environment.GetEnvironmentVariable("IMTBL_API_KEY") ?? "",
    Service = "my-minimal-api",
    Env = builder.Environment.EnvironmentName,
    SkipPaths = new() { "/health", "/metrics" },
});
builder.Services.AddSingleton<ImmutableLogMiddleware>();

var app = builder.Build();

// Registre antes de mapear os endpoints.
app.UseMiddleware<ImmutableLogMiddleware>();

app.MapGet("/health", () => Results.Ok(new { ok = true }));
app.MapGet("/users", () => Results.Ok(new[] { "alice", "bob" }));

app.Run();

Nunca coloque o token no código. Carregue IMTBL_API_KEY de variáveis de ambiente ou do user-secrets em desenvolvimento.

Evento e trilha por endpoint

Receba o `HttpContext` no delegate do endpoint e defina `Items["imtbl.eventName"]` e `Items["imtbl.trail"]`. O middleware lê esses valores ao emitir o evento.

csharp

// Receba o HttpContext para definir evento/trilha por endpoint.
app.MapPost("/payments", (HttpContext ctx, PaymentDto dto) =>
{
    ctx.Items["imtbl.eventName"] = "payment.created";
    ctx.Items["imtbl.trail"] = "order-7782";

    // ... business logic ...
    return Results.Ok(new { ok = true, payment_id = "pay_123" });
});

// Trilha por fluxo de negócio:
app.MapPost("/flows/{id}/run", (HttpContext ctx, string id) =>
{
    ctx.Items["imtbl.trail"] = $"flow-{id}";
    return Results.Ok(new { status = "ok" });
});

Padrão automático: http.METHOD.path.

Trilha imutável (immutable_trail)

A trilha agrupa eventos relacionados em uma mesma linha do tempo auditável. Defina `ctx.Items["imtbl.trail"]` no delegate do endpoint, ou propague entre serviços com o header `X-Imtbl-Trail`. O valor é normalizado pelo middleware antes do envio.

A trilha não pode ser vazia, exceder 256 caracteres ou conter `:` — violações retornam `400 invalid_immutable_trail`. O `SanitizeTrail` do middleware corrige o valor antes do envio.

Resposta e códigos de status

A API de ingestão é assíncrona. Sucesso retorna 202 (novo) ou 200 (duplicata idempotente). Como o middleware é fire-and-forget, esses códigos importam principalmente se você enviar eventos manualmente.

Status	Significado
202	Evento aceito e enfileirado (novo)
200	Idempotency-Key já existente — duplicate: true
400	Idempotency-Key ausente/vazia ou invalid_immutable_trail
403	Assinatura inativa/expirada, escopo ou retenção
413	payload_too_large (limite do servidor: 16KB)
429	monthly_limit_exceeded — não fazer retry
503	mempool_full — transitório, pode dar retry

Esta documentação reflete o comportamento atual da integração. Para dúvidas ou integrações avançadas, entre em contato com o time de suporte.