API'lere genel bakış

ASP.NET Core, HTTP API'leri oluşturmaya yönelik iki yaklaşım sağlar: En az API'ler ve denetleyici tabanlı API'ler. Yeni projeler için, minimum kod ve yapılandırma ile API'ler oluşturmak için basitleştirilmiş, yüksek performanslı bir yaklaşım sağladığı için En Düşük API'leri kullanmanızı öneririz.

Minimum API'ler - Yeni projeler için önerilir

En düşük API'ler, ASP.NET Core ile hızlı HTTP API'leri oluşturmak için önerilen yaklaşımdır. Bunlar, en az kod ve yapılandırma ile tam işlevli uç noktalar oluşturmanıza REST olanak tanır. Geleneksel yapı iskelesini atlayın ve API yollarını ve eylemlerini akıcı bir şekilde bildirerek gereksiz denetleyicilerden kaçının.

Aşağıda web uygulamasının kökünde bir API oluşturan basit bir örnek verilmişti:

var app = WebApplication.Create(args);

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

app.Run();

Çoğu API, parametreleri yolun bir parçası olarak kabul eder:

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

En düşük API'ler birden çok API'ye ölçeklendirmek, karmaşık yolları işlemek, yetkilendirme kuralları uygulamak ve API yanıtlarının içeriğini denetlemek için gereken yapılandırma ve özelleştirmeyi destekler.

En Düşük API'leri kullanmaya başlama

• Öğretici: Öğretici: ASP.NET Core ile minimum API oluşturma
• Hızlı başvuru: Minimum API hızlı başvurusu
• Örnekler: Kod örnekleri içeren yaygın senaryoların tam listesi için bkz. Minimum API'ler hızlı başvurusu

Denetleyici tabanlı API'ler - Alternatif yaklaşım

ASP.NET Core, denetleyicilerin 'den ControllerBasetüretilen sınıflar olduğu denetleyici tabanlı bir yaklaşımı da destekler. Bu yaklaşım, geleneksel nesne odaklı desenleri izler ve şunlar için tercih edilebilir:

• Karmaşık iş mantığına sahip büyük uygulamalar
• MVC desenini bilen ekipler
• Belirli MVC özellikleri gerektiren uygulamalar

Denetleyiciler temelinde bir API için örnek kod aşağıda verilmiştir:

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

Aşağıdaki kod, önerilen En Düşük API yaklaşımını kullanarak aynı işlevselliği sağlar:

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

Her iki API projesi de aşağıdaki sınıfa başvurur:

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

Yaklaşımlar arasında seçim

Yeni projeler için En Düşük API'lerle başlayın. Şu teklifler sunulur:

• Daha basit söz dizimi - Daha az ortak kod
• Daha iyi performans - Denetleyicilere kıyasla daha az ek yük
• Daha kolay test - Basitleştirilmiş birim ve tümleştirme testi
• Modern yaklaşım - En son .NET özelliklerinden yararlanıyor

Aşağıdakilere ihtiyacınız varsa denetleyici tabanlı API'leri göz önünde bulundurun:

• Model bağlama genişletilebilirliği (IModelBinderProvider, IModelBinder)
• Gelişmiş doğrulama özellikleri (IModelValidator)
• Uygulama parçaları veya uygulama modeli
• JsonPatch desteği
• OData desteği

Bu özelliklerin çoğu özel çözümlerle Minimal API'lerde uygulanabilir, ancak denetleyiciler bunları kullanıma sunmaz.

Ayrıca bkz.

• Öğretici: ASP.NET Core ile minimum API oluşturma - Minimal API öğreticisi
• En az API hızlı başvurusu - Minimum API hızlı başvurusu
• ASP.NET Core ile web API'leri oluşturma - Denetleyici tabanlı API'lere genel bakış
• Öğretici: ASP.NET Core ile denetleyici tabanlı web API'si oluşturma - Denetleyici tabanlı API öğreticisi