Vue d’ensemble des API

ASP.NET Core fournit deux approches pour la création d’API HTTP : api minimales et API basées sur un contrôleur. Pour les nouveaux projets, nous vous recommandons d’utiliser des API minimales , car elles fournissent une approche simplifiée et hautes performances pour la création d’API avec un code et une configuration minimes.

API minimales - Recommandé pour les nouveaux projets

Les API minimales sont l’approche recommandée pour créer des API HTTP rapides avec ASP.NET Core. Ils vous permettent de générer des points de terminaison entièrement fonctionnels REST avec un code et une configuration minimes. Ignorez la génération automatique traditionnelle et évitez les contrôleurs inutiles en déclarant couramment des itinéraires et des actions d’API.

Voici un exemple simple qui crée une API à la racine de l’application web :

var app = WebApplication.Create(args);

app.MapGet("/", () => "Hello World!");

app.Run();

La plupart des API acceptent les paramètres dans le cadre de l’itinéraire :

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/users/{userId}/books/{bookId}", 
    (int userId, int bookId) => $"The user id is {userId} and book id is {bookId}");

app.Run();

Les API minimales prennent en charge la configuration et la personnalisation nécessaires pour effectuer une mise à l’échelle vers plusieurs API, gérer des itinéraires complexes, appliquer des règles d’autorisation et contrôler le contenu des réponses d’API.

Prise en main des API minimales

• Tutoriel: Créer une API minimale avec ASP.NET Core
• Référence rapide : Informations de référence rapides sur les API minimales
• Exemples : Pour obtenir une liste complète des scénarios courants avec des exemples de code, consultez la référence rapide des API minimales

API basées sur le contrôleur - Autre approche

ASP.NET Core prend également en charge une approche basée sur un contrôleur où les contrôleurs sont des classes dérivées ControllerBase. Cette approche suit les modèles traditionnels orientés objet et peut être préférée pour :

• Applications volumineuses avec une logique métier complexe
• Teams familiarisé avec le modèle MVC
• Applications nécessitant des fonctionnalités MVC spécifiques

Voici un exemple de code pour une API basée sur des contrôleurs :

namespace APIWithControllers;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        builder.Services.AddControllers();
        var app = builder.Build();

        app.UseHttpsRedirection();

        app.MapControllers();

        app.Run();
    }
}

using Microsoft.AspNetCore.Mvc;

namespace APIWithControllers.Controllers;
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    private static readonly string[] Summaries = new[]
    {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };

    private readonly ILogger<WeatherForecastController> _logger;

    public WeatherForecastController(ILogger<WeatherForecastController> logger)
    {
        _logger = logger;
    }

    [HttpGet(Name = "GetWeatherForecast")]
    public IEnumerable<WeatherForecast> Get()
    {
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = Summaries[Random.Shared.Next(Summaries.Length)]
        })
        .ToArray();
    }
}

Le code suivant fournit les mêmes fonctionnalités à l’aide de l’approche d’API minimale recommandée :

namespace MinimalAPI;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        var app = builder.Build();

        app.UseHttpsRedirection();

        var summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        app.MapGet("/weatherforecast", (HttpContext httpContext) =>
        {
            var forecast = Enumerable.Range(1, 5).Select(index =>
                new WeatherForecast
                {
                    Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                    TemperatureC = Random.Shared.Next(-20, 55),
                    Summary = summaries[Random.Shared.Next(summaries.Length)]
                })
                .ToArray();
            return forecast;
        });

        app.Run();
    }
}

Les deux projets d’API font référence à la classe suivante :

namespace APIWithControllers;

public class WeatherForecast
{
    public DateOnly Date { get; set; }

    public int TemperatureC { get; set; }

    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

    public string? Summary { get; set; }
}

Choix entre les approches

Commencez par des API minimales pour les nouveaux projets. Ils offrent :

• Syntaxe plus simple - Code moins réutilisable
• Meilleures performances - Réduction de la surcharge par rapport aux contrôleurs
• Test plus facile - Tests unitaires et d’intégration simplifiés
• Approche moderne : tire parti des dernières fonctionnalités .NET

Envisagez les API basées sur le contrôleur si vous avez besoin des éléments suivants :

• Extensibilité de liaison de modèle (IModelBinderProvider, IModelBinder)
• Fonctionnalités de validation avancées (IModelValidator)
• Parties d’application ou modèle d’application
• Prise en charge de JsonPatch
• Prise en charge d’OData

La plupart de ces fonctionnalités peuvent être implémentées dans des API minimales avec des solutions personnalisées, mais les contrôleurs les fournissent hors de la boîte de dialogue.

Voir aussi

• Tutoriel : Créer une API minimale avec ASP.NET Core - Didacticiel sur l’API minimale
• Informations de référence rapides sur les API minimales - Informations de référence rapides sur les API minimales
• Créer des API web avec ASP.NET Core - Vue d’ensemble des API basées sur le contrôleur
• Tutoriel : Créer une API web basée sur un contrôleur avec ASP.NET Core - Didacticiel sur l’API basée sur le contrôleur