API-k áttekintése

ASP.NET Core két módszert kínál a HTTP API-k létrehozásához: minimális API-k és vezérlőalapú API-k. Új projektek esetén javasoljuk, hogy minimális API-kat használjon, mivel egyszerűsített, nagy teljesítményű megközelítést biztosítanak az API-k minimális kóddal és konfigurációval történő létrehozásához.

Minimális API-k – Új projektekhez ajánlott

A minimális API-k használata ajánlott a gyors HTTP API-k ASP.NET Core-val való létrehozásához. Lehetővé teszik teljes körűen működő REST végpontok létrehozását minimális kóddal és konfigurációval. Hagyja ki a hagyományos állványzatot, és kerülje a szükségtelen vezérlőket az API-útvonalak és műveletek folyékony deklarálásával.

Íme egy egyszerű példa, amely létrehoz egy API-t a webalkalmazás gyökerénél:

var app = WebApplication.Create(args);

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

app.Run();

A legtöbb API az útvonal részeként fogadja el a paramétereket:

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

A minimális API-k támogatják a több API-ra való skálázáshoz, az összetett útvonalak kezeléséhez, az engedélyezési szabályok alkalmazásához és az API-válaszok tartalmának szabályozásához szükséges konfigurációt és testreszabást.

A minimális API-k használatának első lépései

• Oktatóanyag: Oktatóanyag: Minimális API létrehozása ASP.NET Core használatával
• Rövid útmutató: Minimális API-k gyorshivatkozása
• Példák: A gyakori forgatókönyvek teljes listájáért lásd a minimális API-kat ismertető rövid útmutatót

Vezérlőalapú API-k – Alternatív megközelítés

ASP.NET Core olyan vezérlőalapú megközelítést is támogat, amelyből a vezérlők származnak ControllerBase. Ez a megközelítés a hagyományos objektumorientált mintákat követi, és előnyben részesíthető a következőkhöz:

• Nagy alkalmazások összetett üzleti logikával
• Az MVC-mintát ismerő csapatok
• Adott MVC-funkciókat igénylő alkalmazások

Az alábbi mintakód egy vezérlőn alapuló API-hoz:

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

Az alábbi kód ugyanazokat a funkciókat biztosítja az ajánlott Minimal API-megközelítéssel:

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

Mindkét API-projekt a következő osztályra hivatkozik:

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

Választás a megközelítések között

Kezdje minimális API-kkal az új projektekhez. A következő lehetőségeket kínálják:

• Egyszerűbb szintaxis – Kevesebb sablonkód
• Jobb teljesítmény – Kevesebb többletterhelés a vezérlőkhöz képest
• Egyszerűbb tesztelés – Egyszerűsített egység- és integrációs tesztelés
• Modern megközelítés – Kihasználja a legújabb .NET-funkciókat

Szükség esetén fontolja meg a vezérlőalapú API-kat :

• Modellkötés bővíthetősége (IModelBinderProvider, IModelBinder)
• Speciális érvényesítési funkciók (IModelValidator)
• Alkalmazásrészek vagy az alkalmazásmodell
• JsonPatch-támogatás
• OData-támogatás

Ezeknek a funkcióknak a többsége egyéni megoldásokkal implementálható minimális API-kban, de a vezérlők a dobozon kívül biztosítják őket.

Lásd még

• Oktatóanyag: Minimális API létrehozása a ASP.NET Core használatával – Minimális API-oktatóanyag
• Minimális API-k gyorshivatkozása – Minimális API-k gyorshivatkozása
• Webes API-k létrehozása a ASP.NET Core használatával – Vezérlőalapú API-k áttekintése
• Oktatóanyag: Vezérlőalapú webes API létrehozása a ASP.NET Core használatával – Vezérlőalapú API-oktatóanyag