Přehled rozhraní API

ASP.NET Core poskytuje dva přístupy k vytváření rozhraní API HTTP: minimální rozhraní API a rozhraní API založená na kontroleru. U nových projektů doporučujeme používat minimální rozhraní API, protože poskytují zjednodušený a vysoce výkonný přístup pro vytváření rozhraní API s minimálním kódem a konfigurací.

Minimální rozhraní API – doporučeno pro nové projekty

Minimální rozhraní API jsou doporučeným přístupem k vytváření rychlých rozhraní API HTTP s ASP.NET Core. Umožňují vytvářet plně funkční REST koncové body s minimálním kódem a konfigurací. Přeskočte tradiční generování uživatelského rozhraní a vyhněte se zbytečným kontrolerů tím, že deklarují trasy a akce rozhraní API.

Tady je jednoduchý příklad, který vytvoří rozhraní API v kořenovém adresáři webové aplikace:

var app = WebApplication.Create(args);

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

app.Run();

Většina rozhraní API přijímá parametry jako součást 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();

Minimální rozhraní API podporují konfiguraci a přizpůsobení potřebné ke škálování na více rozhraní API, zpracování složitých tras, použití autorizačních pravidel a řízení obsahu odpovědí rozhraní API.

Začínáme s minimálními rozhraními API

• Kurz: Kurz: Vytvoření minimálního rozhraní API s ASP.NET Core
• Stručná referenční příručka: Stručná referenční dokumentace k minimálním rozhraním API
• Příklady: Úplný seznam běžných scénářů s příklady kódu najdete v rychlých referenčních informacích k minimálním rozhraním API.

Rozhraní API založená na kontroleru – alternativní přístup

ASP.NET Core také podporuje přístup založený na kontroleru, kde kontrolery jsou třídy odvozené z ControllerBase. Tento přístup se řídí tradičními objektově orientovanými vzory a může být upřednostňovaný pro:

• Velké aplikace s komplexní obchodní logikou
• Teams obeznámené se vzorem MVC
• Aplikace vyžadující specifické funkce MVC

Tady je ukázkový kód pro rozhraní API na základě kontrolerů:

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

Následující kód poskytuje stejné funkce pomocí doporučeného přístupu k minimálnímu rozhraní 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 rozhraní API odkazují na následující třídu:

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

Volba mezi přístupy

Začněte s minimálními rozhraními API pro nové projekty. Nabízejí:

• Jednodušší syntaxe – méně často používaný kód
• Lepší výkon – snížení režie oproti kontrolerů
• Jednodušší testování – Zjednodušené testování jednotek a integračního testování
• Moderní přístup – využívá nejnovější funkce .NET.

Pokud potřebujete, zvažte rozhraní API založená na kontroleru:

• Rozšiřitelnost vazby modelu (IModelBinderProvider, IModelBinder)
• Pokročilé funkce ověřování (IModelValidator)
• Aplikační části nebo aplikační model
• Podpora jsonPatch
• Podpora OData

Většinu těchto funkcí je možné implementovat v minimálních rozhraních API s vlastními řešeními, ale kontrolery je poskytují předem.

Viz také

• Kurz: Vytvoření minimálního rozhraní API pomocí ASP.NET Core – kurz minimálního rozhraní API
• Stručná referenční příručka k minimálním rozhraním API – Stručná referenční příručka k minimálním rozhraním API
• Vytváření webových rozhraní API s využitím ASP.NET Core – Přehled rozhraní API založených na kontroleru
• Kurz: Vytvoření webového rozhraní API založeného na kontroleru s využitím ASP.NET Core – kurz rozhraní API založený na kontroleru