APIs: styles, design, auth, performance & rate limiting

// .NET 10: stream server-sent events from a minimal API
app.MapGet("/payments/{id}/status", (string id, PaymentEvents events, CancellationToken ct) =>
    TypedResults.ServerSentEvents(events.WatchAsync(id, ct), eventType: "status"));

builder.Services.AddOpenApi();          // document at /openapi/v1.json
builder.Services.AddProblemDetails();   // consistent RFC 9457 errors
builder.Services.AddValidation();       // .NET 10: [Required], [Range] etc. on parameters -> 400

var app = builder.Build();
app.UseExceptionHandler();              // unhandled exceptions -> ProblemDetails 500
app.MapOpenApi();
app.MapScalarApiReference();            // UI at /scalar

app.MapPost("/v1/payments", async (CreatePayment cmd, PaymentService svc, CancellationToken ct) =>
{
    var payment = await svc.CreateAsync(cmd, ct);
    return TypedResults.Created($"/v1/payments/{payment.Id}", payment);   // 201 + Location
});

ETags aren't automatic. Return an ETag header from a row version, read If-Match (EntityTagHeaderValue) and return 412 when it doesn't match.

public sealed class AccountOwner : IAuthorizationRequirement;

public sealed class AccountOwnerHandler : AuthorizationHandler<AccountOwner, Account>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext ctx, AccountOwner req, Account account)
    {
        if (account.OwnerId == ctx.User.FindFirst("oid")?.Value) ctx.Succeed(req);
        return Task.CompletedTask;
    }
}
// builder.Services.AddSingleton<IAuthorizationHandler, AccountOwnerHandler>();

app.MapGet("/accounts/{id:int}", async (int id, AppDbContext db,
    IAuthorizationService auth, ClaimsPrincipal user) =>
{
    var account = await db.Accounts.FindAsync(id);
    if (account is null) return Results.NotFound();
    var check = await auth.AuthorizeAsync(user, account, new AccountOwner());  // can THIS user see THIS account?
    return check.Succeeded ? Results.Ok(account) : Results.Forbid();          // 403
}).RequireAuthorization();                                                     // 401 if not signed in

// API: validate Entra ID tokens and require a scope
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));
builder.Services.AddAuthorizationBuilder()
    .AddPolicy("payments.write", p => p.RequireScope("payments.write"));

// Batch job: client credentials with a certificate (no user, no secret)
var msal = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithCertificate(certificate)
    .WithAuthority($"https://login.microsoftonline.com/{tenantId}")
    .Build();
var result = await msal.AcquireTokenForClient(["api://payments/.default"]).ExecuteAsync();

Login without passwords: ASP.NET Core Identity in .NET 10 supports passkeys (WebAuthn / FIDO2).

// Keyset pagination: fast and stable on deep pages (needs an index on Id)
app.MapGet("/payments", (long? after, AppDbContext db, CancellationToken ct) =>
    db.Payments.AsNoTracking()
        .Where(p => after == null || p.Id > after)
        .OrderBy(p => p.Id)
        .Take(50)
        .Select(p => new PaymentDto(p.Id, p.Amount, p.Status))   // only the columns needed
        .ToListAsync(ct));

// Fan out independent downstream calls together, not one after another
var customerTask = customers.GetAsync(id, ct);
var accountsTask = accounts.ListAsync(id, ct);
await Task.WhenAll(customerTask, accountsTask);

Measure with OpenTelemetry traces, dotnet-counters and a load test before tuning. Response compression over HTTPS is off by default because of BREACH-style attacks on secrets in responses.

builder.Services.AddRateLimiter(o =>
{
    o.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
    o.AddPolicy("per-api-key", http => RateLimitPartition.GetTokenBucketLimiter(
        partitionKey: http.Request.Headers["X-Api-Key"].ToString() is { Length: > 0 } key
            ? key : $"ip:{http.Connection.RemoteIpAddress}",
        factory: _ => new TokenBucketRateLimiterOptions
        {
            TokenLimit = 100,                              // bucket size B (max burst)
            TokensPerPeriod = 10,                          // refill r ...
            ReplenishmentPeriod = TimeSpan.FromSeconds(1), // ... per second
            QueueLimit = 0                                 // reject at once, don't queue
        }));
    o.OnRejected = (ctx, ct) =>
    {
        if (ctx.Lease.TryGetMetadata(MetadataName.RetryAfter, out var retryAfter))
            ctx.HttpContext.Response.Headers.RetryAfter = ((int)Math.Ceiling(retryAfter.TotalSeconds)).ToString();
        return ValueTask.CompletedTask;
    };
});

var app = builder.Build();
app.UseRateLimiter();
app.MapPost("/payments", CreatePayment).RequireRateLimiting("per-api-key");

Built-in limiters count per instance (10 nodes = 10× the limit). Authenticate the key before using it as a partition, or callers can invent keys to get fresh buckets. On the client side, Microsoft.Extensions.Http.Resilience retries honour Retry-After.

public sealed class IdempotencyFilter(IDistributedCache cache) : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext ctx, EndpointFilterDelegate next)
    {
        var http = ctx.HttpContext;
        string? key = http.Request.Headers["Idempotency-Key"];
        if (string.IsNullOrWhiteSpace(key))
            return TypedResults.Problem("Idempotency-Key header is required", statusCode: 400);

        var cacheKey = $"idem:{http.User.FindFirst("azp")?.Value}:{key}";   // scope keys per client
        if (await cache.GetStringAsync(cacheKey) is { } saved)
            return TypedResults.Text(saved, "application/json");          // replay, don't charge twice

        var result = await next(ctx);
        if (result is IValueHttpResult { Value: { } value })
            await cache.SetStringAsync(cacheKey, JsonSerializer.Serialize(value, JsonSerializerOptions.Web),
                new DistributedCacheEntryOptions { AbsoluteExpirationRelativeToNow = TimeSpan.FromHours(24) });
        return result;
    }
}
// app.MapPost("/payments", CreatePayment).AddEndpointFilter<IdempotencyFilter>();

This sketch has a race: two identical requests arriving together both run. Claim the key first (Redis SET NX or the unique index), store a hash of the body to reject the same key with a different payload (422), and replay the original status code too.

[assembly: DataLoaderModule("BankDataLoaders")]

builder.Services.AddBankDataLoaders();           // generated from [DataLoader] methods
builder.Services
    .AddGraphQLServer()
    .AddTypes()                                  // generated from [QueryType], [ObjectType<T>]
    .ModifyCostOptions(o => { o.MaxFieldCost = 2_000; o.MaxTypeCost = 5_000; });
app.MapGraphQL();                                // POST /graphql

[QueryType]
public static partial class AccountQueries
{
    public static IQueryable<Account> GetAccounts(BankDb db) => db.Accounts.OrderBy(a => a.Id);
}

[ObjectType<Account>]
public static partial class AccountNode
{
    public static Task<Customer?> GetOwnerAsync(
        [Parent] Account account, ICustomerByIdDataLoader byId, CancellationToken ct)
        => byId.LoadAsync(account.CustomerId, ct);   // batched: no N+1
}

internal static class CustomerDataLoaders
{
    [DataLoader]
    public static Task<Dictionary<int, Customer>> GetCustomerByIdAsync(
        IReadOnlyList<int> ids, BankDb db, CancellationToken ct)
        => db.Customers.Where(c => ids.Contains(c.Id)).ToDictionaryAsync(c => c.Id, ct);
}

Keep every HotChocolate.* package on the same version. 16.6.x is the stable line; 16.7 builds are preview.