Omówienie interfejsów API

ASP.NET Core udostępnia dwa podejścia do tworzenia interfejsów API HTTP: minimalne interfejsy API i interfejsy API oparte na kontrolerach. W przypadku nowych projektów zalecamy używanie minimalnych interfejsów API, ponieważ zapewniają uproszczone, wysokowydajne podejście do tworzenia interfejsów API z minimalnym kodem i konfiguracją.

Minimalne interfejsy API — zalecane w przypadku nowych projektów

Minimalne interfejsy API są zalecanym podejściem do tworzenia szybkich interfejsów API HTTP za pomocą ASP.NET Core. Umożliwiają one tworzenie w pełni działających REST punktów końcowych z minimalnym kodem i konfiguracją. Pomiń tradycyjne tworzenie szkieletów i unikaj niepotrzebnych kontrolerów, płynnie deklarując trasy i akcje interfejsu API.

Oto prosty przykład, który tworzy interfejs API w katalogu głównym aplikacji internetowej:

var app = WebApplication.Create(args);

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

app.Run();

Większość interfejsów API akceptuje parametry w ramach trasy:

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

Minimalne interfejsy API obsługują konfigurację i dostosowywanie wymagane do skalowania do wielu interfejsów API, obsługę złożonych tras, stosowanie reguł autoryzacji i kontrolowanie zawartości odpowiedzi interfejsu API.

Wprowadzenie do minimalnych interfejsów API

• Samouczek: samouczek: tworzenie minimalnego interfejsu API przy użyciu platformy ASP.NET Core
• Szybka dokumentacja: krótki przewodnik po interfejsach API
• Przykłady: Aby uzyskać pełną listę typowych scenariuszy z przykładami kodu, zobacz Krótkie omówienie interfejsów API

Interfejsy API oparte na kontrolerach — alternatywne podejście

ASP.NET Core obsługuje również podejście oparte na kontrolerach, w którym kontrolery są klasami pochodzącymi z ControllerBaseklasy . Takie podejście jest zgodne z tradycyjnymi wzorcami zorientowanymi na obiekty i może być preferowane dla:

• Duże aplikacje ze złożoną logiką biznesową
• Zespoły zaznajomione ze wzorcem MVC
• Aplikacje wymagające określonych funkcji MVC

Oto przykładowy kod interfejsu API oparty na kontrolerach:

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

Poniższy kod udostępnia te same funkcje przy użyciu zalecanego podejścia minimalnego interfejsu API:

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

Oba projekty interfejsu API odwołują się do następującej klasy:

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

Wybieranie między podejściami

Zacznij od minimalnych interfejsów API dla nowych projektów. Oferują one:

• Prostsza składnia — mniej standardowy kod
• Lepsza wydajność — zmniejszenie nakładu pracy w porównaniu z kontrolerami
• Łatwiejsze testowanie — uproszczone testowanie jednostkowe i integracyjne
• Nowoczesne podejście — wykorzystuje najnowsze funkcje platformy .NET

W razie potrzeby rozważ użycie interfejsów API opartych na kontrolerze:

• Rozszerzalność powiązania modelu (IModelBinderProvider, IModelBinder)
• Zaawansowane funkcje walidacji (IModelValidator)
• Części aplikacji lub model aplikacji
• Obsługa kodu JsonPatch
• Obsługa OData

Większość tych funkcji można zaimplementować w interfejsach API z minimalnymi interfejsami API z niestandardowymi rozwiązaniami, ale kontrolery udostępniają je z pudełka.

Zobacz też

• Samouczek: tworzenie minimalnego interfejsu API przy użyciu ASP.NET Core — samouczek dotyczący minimalnego interfejsu API
• Krótkie informacje o minimalnych interfejsach API — krótkie informacje o interfejsach API
• Tworzenie internetowych interfejsów API za pomocą ASP.NET Core — omówienie interfejsów API opartych na kontrolerach
• Samouczek: tworzenie internetowego interfejsu API opartego na kontrolerze przy użyciu ASP.NET Core — samouczek dotyczący interfejsu API opartego na kontrolerach