Minimal API, ASP.NET Core ile az kodla HTTP servisleri geliştirmeyi sağlayan yaklaşımdır. Controller sınıfları yazmadan, doğrudan Program.cs içinde veya düzenli uzantı metotlarında endpoint tanımlanır. Küçük servisler, mikro servisler ve entegrasyon uç noktaları için oldukça pratiktir.
İlk örnek
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/api/merhaba", () => Results.Ok(new { mesaj = "Merhaba dünya" }));
app.Run();
Birkaç satırla çalışan bir API elde edilir.
Controller yaklaşımından farkı
Klasik ASP.NET Core Web API yaklaşımında her kaynak için bir controller sınıfı ve action metotları yazılır. Minimal API'de ise endpoint'ler doğrudan lambda veya metot olarak tanımlanır.
- Minimal API: Daha az tören (ceremony), daha hızlı başlangıç, küçük ve odaklı servisler için ideal.
- Controller: Büyük ve çok ekipli projelerde alışılmış yapı, filtreler ve konvansiyonlar.
İki yaklaşım aynı projede birlikte de kullanılabilir.
Dependency injection ve servisler
builder.Services.AddScoped<IUrunServisi, UrunServisi>();
app.MapGet("/api/urunler/{id:int}", async (int id, IUrunServisi servis) =>
{
var urun = await servis.GetirAsync(id);
return urun is null ? Results.NotFound() : Results.Ok(urun);
});
Parametredeki servis, dependency injection ile otomatik olarak sağlanır.
Endpoint gruplama
Proje büyüdükçe endpoint'leri gruplamak düzeni korur:
var urunler = app.MapGroup("/api/urunler")
.RequireAuthorization();
urunler.MapGet("/", async (IUrunServisi s) => await s.ListeleAsync());
urunler.MapPost("/", async (UrunEkleDto dto, IUrunServisi s) =>
{
var yeni = await s.EkleAsync(dto);
return Results.Created($"/api/urunler/{yeni.Id}", yeni);
});
Grupları ayrı dosyalarda uzantı metotları olarak tanımlamak, Program.cs dosyasının şişmesini önler.
Doğrulama
Gelen verinin doğrulanması güvenli bir API'nin temelidir. Güncel ASP.NET Core sürümlerinde Minimal API'ler için veri açıklama (data annotation) tabanlı yerleşik doğrulama desteği bulunur. Daha karmaşık kurallar için doğrulama kütüphaneleri veya endpoint filtreleri kullanılabilir. Doğrulama hatalarında tutarlı bir hata formatı (örneğin Problem Details) döndürmek istemci tarafını kolaylaştırır.
OpenAPI dokümantasyonu
ASP.NET Core, API'nizin OpenAPI tanımını üretmeyi destekler. Bu tanım; istemci kodu üretmek, test etmek ve ekip içinde paylaşmak için kullanılır.
builder.Services.AddOpenApi();
app.MapOpenApi();
Kimlik doğrulama ve yetkilendirme
JWT tabanlı kimlik doğrulama, API'ler için yaygın bir tercihtir. Ayrıntılar için JWT ile kimlik doğrulama yazımıza bakabilirsiniz. Endpoint veya grup seviyesinde RequireAuthorization() ile koruma eklenir; rol ve politika bazlı yetkilendirme de desteklenir.
Üretim için kontrol listesi
- Hata yönetimi için merkezi bir ara katman (exception handler)
- Yapılandırılmış loglama
- Hız sınırlama (rate limiting) ile kötüye kullanımı önleme
- CORS ayarlarının yalnızca gerekli kaynaklara izin vermesi
- Sağlık kontrolü (health check) endpoint'i
- Gizli anahtarların kod dışında saklanması
Performans önerileri için ASP.NET Core performans optimizasyonu yazısına göz atabilirsiniz.
Sık sorulan sorular
Minimal API büyük projeler için uygun mu?
Evet, ancak düzen için endpoint gruplama, ayrı dosyalar ve servis katmanı kullanmak şarttır. Aksi halde Program.cs hızla okunamaz hale gelir.
Performans farkı var mı?
Minimal API genellikle daha az ek yük ile çalışır; ancak çoğu uygulamada asıl belirleyici veritabanı ve dış servis çağrılarıdır.
Sonuç
Minimal API, ASP.NET Core ile hızlı, sade ve modern web servisleri geliştirmenin etkili bir yoludur. Doğru klasör yapısı, doğrulama ve güvenlik önlemleriyle küçük servislerden kurumsal API'lere kadar kullanılabilir. API geliştirme ve entegrasyon ihtiyaçlarınız için teklif isteyebilirsiniz.