Panoramica delle API

ASP.NET Core offre due approcci per la creazione di API HTTP: API minime e API basate su controller. Per i nuovi progetti, è consigliabile usare API minime perché forniscono un approccio semplificato e ad alte prestazioni per la creazione di API con codice e configurazione minimi.

API minime - Consigliate per i nuovi progetti

Le API minime sono l'approccio consigliato per la creazione di API HTTP veloci con ASP.NET Core. Consentono di creare endpoint completamente funzionanti REST con codice e configurazione minimi. Ignorare lo scaffolding tradizionale ed evitare controller non necessari dichiarando in modo fluente le route e le azioni dell'API.

Ecco un semplice esempio che crea un'API nella radice dell'app Web:

var app = WebApplication.Create(args);

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

app.Run();

La maggior parte delle API accetta parametri come parte della route:

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();

Le API minime supportano la configurazione e la personalizzazione necessarie per ridimensionare più API, gestire route complesse, applicare regole di autorizzazione e controllare il contenuto delle risposte api.

Introduzione alle API minime

• Esercitazione: Esercitazione: Creare un'API minima con ASP.NET Core
• Riferimento rapido: Informazioni di riferimento rapido sulle API minime
• Esempi: per un elenco completo degli scenari comuni con esempi di codice, vedere Informazioni di riferimento rapido sulle API minime

API basate su controller - Approccio alternativo

ASP.NET Core supporta anche un approccio basato su controller in cui i controller sono classi che derivano da ControllerBase. Questo approccio segue modelli tradizionali orientati agli oggetti e può essere preferibile per:

• Applicazioni di grandi dimensioni con logica di business complessa
• Team che hanno familiarità con il modello MVC
• Applicazioni che richiedono funzionalità MVC specifiche

Ecco il codice di esempio per un'API basata sui controller:

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();
    }
}

Il codice seguente fornisce la stessa funzionalità usando l'approccio consigliato per l'API minima:

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();
    }
}

Entrambi i progetti API fanno riferimento alla classe seguente:

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; }
}

Scelta tra approcci

Iniziare con le API minime per i nuovi progetti. Offrono:

• Sintassi più semplice - Codice boilerplate minore
• Prestazioni migliori - Riduzione del sovraccarico rispetto ai controller
• Test semplificati - Test di unità e integrazione semplificati
• Approccio moderno : sfrutta le funzionalità più recenti di .NET

Se necessario, prendere in considerazione le API basate su controller:

• Estendibilità dell'associazione di modelli (IModelBinderProvider, IModelBinder)
• Funzionalità di convalida avanzate (IModelValidator)
• Parti dell'applicazione o modello di applicazione
• Supporto jsonPatch
• Supporto di OData

La maggior parte di queste funzionalità può essere implementata in API minime con soluzioni personalizzate, ma i controller li forniscono automaticamente.

Vedi anche

• Esercitazione: Creare un'API minima con ASP.NET Core - Esercitazione api minima
• Informazioni di riferimento rapido sulle API minime - Informazioni di riferimento rapido sulle API minime
• Creare API Web con ASP.NET Core - Panoramica delle API basate su controller
• Esercitazione: Creare un'API Web basata su controller con ASP.NET Core - Esercitazione sull'API basata su controller