API REST avec ASP.NET Core

Le pipeline de middleware Junior

Chaque requête traverse les middlewares dans l'ordre d'enregistrement, atteint l'endpoint, puis la réponse remonte dans l'ordre inverse. L'ordre est sémantique : l'authentification doit précéder l'autorisation, la gestion d'erreurs doit envelopper tout le reste.

Program.cs — ordre recommandé

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddProblemDetails();
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorizationBuilder()
    .AddPolicy("orders:write", p => p.RequireClaim("scope", "orders.write"));
builder.Services.AddRateLimiter(o => o.AddFixedWindowLimiter("api", w =>
    { w.PermitLimit = 100; w.Window = TimeSpan.FromMinutes(1); }));
builder.Services.AddOpenApi();                 // OpenAPI intégré depuis .NET 9
builder.Services.AddHealthChecks().AddDbContextCheck<ShopDbContext>();

var app = builder.Build();

app.UseExceptionHandler();                     // 1. enveloppe tout
if (!app.Environment.IsDevelopment()) app.UseHsts();
app.UseHttpsRedirection();
app.UseCors("front");                          // avant l'auth pour les preflight
app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();

app.MapOpenApi();
app.MapHealthChecks("/health/ready");
app.MapOrders();                               // groupes d'endpoints par fonctionnalité
app.Run();

Controllers, Minimal APIs ou FastEndpoints Junior

Le contrat HTTP Junior

Erreurs normalisées : ProblemDetails (RFC 9457)

{
  "type": "https://api.shop.fr/errors/order-already-submitted",
  "title": "Commande déjà validée",
  "status": 409,
  "detail": "La commande 7f3c… ne peut plus être modifiée.",
  "instance": "/orders/7f3c…/lines",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

public static class OrderEndpoints
{
    public static void MapOrders(this IEndpointRouteBuilder app)
    {
        var g = app.MapGroup("/v1/orders").WithTags("Orders").RequireAuthorization();

        g.MapGet("/{id:guid}", async Task<Results<Ok<OrderDto>, NotFound>> (
            Guid id, IOrderQueries q, CancellationToken ct) =>
            await q.GetAsync(id, ct) is { } dto ? TypedResults.Ok(dto) : TypedResults.NotFound());

        g.MapPost("/", async Task<Results<Created<OrderDto>, ValidationProblem>> (
            CreateOrder cmd, ISender sender, CancellationToken ct) =>
        {
            var dto = await sender.Send(cmd, ct);
            return TypedResults.Created($"/v1/orders/{dto.Id}", dto);
        }).RequireAuthorization("orders:write").RequireRateLimiting("api");
    }
}

Points de conception

• Versionnement : dans l'URL (/v1/) pour la lisibilité, ou par en-tête ; package Asp.Versioning.Http. Ne jamais casser un contrat publié.
• Pagination : par curseur (?after=…&limit=50) pour les gros volumes, l'offset devient lent et instable quand les données bougent.
• Concurrence optimiste : renvoyer un ETag, exiger If-Match sur PUT/PATCH, répondre 412 en cas de conflit.
• Idempotence des POST : en-tête Idempotency-Key stocké avec la réponse ; un rejeu renvoie la même réponse sans retraiter.
• DTO dédiés : ne jamais exposer les entités EF (sur-exposition, boucles de sérialisation, couplage au schéma).

Injection de dépendances : les durées de vie Confirmé