Minimal API (et les API en général)

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<AppDb>(o => o.UseSqlite("Data Source=boutique.db"));
builder.Services.AddOpenApi();

var app = builder.Build();
app.MapOpenApi();                                    // /openapi/v1.json

app.MapGet("/produits", async (AppDb db) =>
    await db.Produits.AsNoTracking().ToListAsync());

app.MapGet("/produits/{id:int}", async (int id, AppDb db) =>
    await db.Produits.FindAsync(id) is Produit p
        ? Results.Ok(p)
        : Results.NotFound());

app.MapPost("/produits", async (Produit nouveau, AppDb db) =>
{
    db.Produits.Add(nouveau);
    await db.SaveChangesAsync();
    return Results.Created($"/produits/{nouveau.Id}", nouveau);
});

app.Run();

// Contraintes de route : filtrées AVANT ton code, renvoient 404 si le format ne colle pas
app.MapGet("/produits/{id:int}", ...);                    // entier seulement
app.MapGet("/clients/{id:guid}", ...);                    // GUID
app.MapGet("/archives/{annee:int:min(2000)}", ...);       // valeur minimale
app.MapGet("/fichiers/{*chemin}", ...);                   // capture le reste, slash inclus
app.MapGet("/pages/{slug:regex(^[a-z0-9-]+$)}", ...);     // expression régulière

// Au lieu de sept paramètres dans la signature
public record FiltreProduits(string? Recherche, decimal? PrixMin, decimal? PrixMax,
                             int Page = 1, int Taille = 20);

app.MapGet("/produits", async ([AsParameters] FiltreProduits f, AppDb db) => { /* ... */ });
// GET /produits?recherche=clavier&prixMin=20&page=2

// TypedResults est préférable à Results : le type de retour est explicite,
// donc testable sans HTTP et automatiquement documenté dans OpenAPI.
app.MapGet("/produits/{id:int}",
    async Task<Results<Ok<Produit>, NotFound>> (int id, AppDb db) =>
    {
        var p = await db.Produits.FindAsync(id);
        return p is null ? TypedResults.NotFound() : TypedResults.Ok(p);
    });

public static class ProduitsEndpoints
{
    public static RouteGroupBuilder MapProduits(this IEndpointRouteBuilder routes)
    {
        var groupe = routes.MapGroup("/produits")
            .WithTags("Produits")                // regroupement dans la documentation OpenAPI
            .RequireAuthorization()              // s'applique à TOUT le groupe
            .WithOpenApi();

        groupe.MapGet("/", Lister);
        groupe.MapGet("/{id:int}", Obtenir).WithName("ObtenirProduit");
        groupe.MapPost("/", Creer).RequireAuthorization("admin");
        groupe.MapPut("/{id:int}", Modifier);
        groupe.MapDelete("/{id:int}", Supprimer).RequireAuthorization("admin");

        return groupe;
    }

    // Des méthodes nommées, pas des lambdas : testables unitairement, lisibles, réutilisables
    private static async Task<Ok<PageDe<ProduitDto>>> Lister(
        [AsParameters] FiltreProduits f, AppDb db, CancellationToken ct)
    {
        var requete = db.Produits.AsNoTracking();

        if (!string.IsNullOrWhiteSpace(f.Recherche))
            requete = requete.Where(p => p.Nom.Contains(f.Recherche));
        if (f.PrixMax is not null)
            requete = requete.Where(p => p.Prix <= f.PrixMax);

        var total = await requete.CountAsync(ct);
        var elements = await requete
            .OrderBy(p => p.Nom).ThenBy(p => p.Id)          // tri STABLE : indispensable en pagination
            .Skip((f.Page - 1) * f.Taille).Take(f.Taille)
            .Select(p => new ProduitDto(p.Id, p.Nom, p.Prix))  // projection : pas d'entité exposée
            .ToListAsync(ct);

        return TypedResults.Ok(new PageDe<ProduitDto>(elements, total, f.Page, f.Taille));
    }

    private static async Task<Results<Ok<ProduitDto>, NotFound>> Obtenir(int id, AppDb db, CancellationToken ct)
        => await db.Produits.AsNoTracking()
               .Where(p => p.Id == id)
               .Select(p => new ProduitDto(p.Id, p.Nom, p.Prix))
               .FirstOrDefaultAsync(ct) is { } dto
           ? TypedResults.Ok(dto)
           : TypedResults.NotFound();

    private static async Task<Created<ProduitDto>> Creer(CreerProduit dto, AppDb db, CancellationToken ct)
    {
        var p = new Produit { Nom = dto.Nom, Prix = dto.Prix };
        db.Produits.Add(p);
        await db.SaveChangesAsync(ct);
        return TypedResults.Created($"/produits/{p.Id}", new ProduitDto(p.Id, p.Nom, p.Prix));
    }
    // … Modifier, Supprimer …
}

// Program.cs redevient un sommaire lisible
app.MapProduits();
app.MapCommandes();
app.MapClients();

builder.Services.AddValidation();      // ASP.NET Core 10 : validation automatique des endpoints

public record CreerProduit(
    [Required, StringLength(120, MinimumLength = 2)] string Nom,
    [Range(0.01, 100_000)]                          decimal Prix,
    [Required, RegularExpression("^[A-Z]{2}-[0-9]{4}$")] string Reference);

app.MapPost("/produits", (CreerProduit dto) => TypedResults.Created("/produits/1", dto));

// Corps invalide → 400 + ProblemDetails détaillant chaque champ, sans une ligne de code :
// { "errors": { "Nom": ["The field Nom must be a string with a minimum length of 2..."] } }

// Désactiver ponctuellement
app.MapPost("/import", Import).DisableValidation();

// Un filtre s'exécute autour du gestionnaire : idéal pour journaliser, mesurer, transformer
public class FiltreChrono(ILogger<FiltreChrono> log) : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext ctx,
                                                EndpointFilterDelegate suivant)
    {
        var chrono = Stopwatch.StartNew();
        var resultat = await suivant(ctx);        // ← appelle le gestionnaire (ou le filtre suivant)
        if (chrono.ElapsedMilliseconds > 500)
            log.LogWarning("Endpoint lent : {Route} en {Ms}ms",
                ctx.HttpContext.Request.Path, chrono.ElapsedMilliseconds);
        return resultat;
    }
}

app.MapProduits().AddEndpointFilter<FiltreChrono>();       // sur tout un groupe

// Version courte, en ligne
app.MapPost("/commandes", Creer)
   .AddEndpointFilter(async (ctx, suivant) =>
   {
        if (!ctx.HttpContext.Request.Headers.ContainsKey("Idempotency-Key"))
            return TypedResults.BadRequest("En-tête Idempotency-Key requis");
        return await suivant(ctx);
   });

builder.Services.AddProblemDetails(o =>
{
    // Enrichir toutes les réponses d'erreur d'un identifiant de corrélation
    o.CustomizeProblemDetails = ctx =>
    {
        ctx.ProblemDetails.Extensions["traceId"] = ctx.HttpContext.TraceIdentifier;
        ctx.ProblemDetails.Instance = ctx.HttpContext.Request.Path;
    };
});
app.UseExceptionHandler();
app.UseStatusCodePages();       // transforme aussi les 404 « vides » en ProblemDetails

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.9",
  "title": "Conflict",
  "status": 409,
  "detail": "Stock insuffisant pour la référence AB-1234 : 3 demandés, 1 disponible.",
  "instance": "/commandes",
  "traceId": "0HN7GKQ2M3F1A:00000003"
}

builder.Services.AddOpenApi(o =>
{
    o.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info = new() { Title = "API Boutique", Version = "v1",
                           Description = "Catalogue et commandes" };
        return Task.CompletedTask;
    });
});

var app = builder.Build();
app.MapOpenApi();                          // document JSON : /openapi/v1.json
app.MapOpenApi("/openapi/{documentName}.yaml");   // .NET 10 : sortie YAML

// Décrire un endpoint
app.MapGet("/produits/{id:int}", Obtenir)
   .WithSummary("Obtient un produit par identifiant")
   .WithDescription("Renvoie 404 si le produit est inconnu ou retiré du catalogue.")
   .Produces<ProduitDto>(StatusCodes.Status200OK)
   .ProducesProblem(StatusCodes.Status404NotFound);

// Server-Sent Events : le serveur pousse des messages sur une connexion HTTP maintenue
app.MapGet("/cours-bourse", (CancellationToken ct) =>
{
    async IAsyncEnumerable<Cours> Suivre([EnumeratorCancellation] CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            yield return new Cours("MSFT", Random.Shared.Next(400, 460), DateTime.UtcNow);
            await Task.Delay(1000, ct);
        }
    }
    return TypedResults.ServerSentEvents(Suivre(ct), eventType: "cours");
});

// Côté navigateur : new EventSource("/cours-bourse").onmessage = e => ...
// Renvoyer un IAsyncEnumerable<T> ordinaire produit un tableau JSON diffusé au fil de l'eau.

// Pagination obligatoire sur toute liste (jamais de « tout renvoyer »)
// Tri stable, sinon la page 2 peut répéter des éléments de la page 1

// Limitation de débit
builder.Services.AddRateLimiter(o => o.AddFixedWindowLimiter("api", l =>
{
    l.Window = TimeSpan.FromMinutes(1);
    l.PermitLimit = 100;
    l.QueueLimit = 0;
}));
app.UseRateLimiter();
app.MapProduits().RequireRateLimiting("api");

// Versionnement (paquet Asp.Versioning.Http)
var v1 = app.NewVersionedApi("Produits").MapGroup("/api/v{version:apiVersion}")
            .HasApiVersion(1.0);

// Compression et cache
app.MapGet("/catalogue", Catalogue).CacheOutput(p => p.Expire(TimeSpan.FromMinutes(5)));

// Contrôle de santé
app.MapHealthChecks("/sante");

// CORS pour un front séparé
builder.Services.AddCors(o => o.AddPolicy("front", p => p
    .WithOrigins("https://boutique.fr")     // ⚠️ jamais AllowAnyOrigin avec des identifiants
    .AllowAnyHeader().AllowAnyMethod()));