Giriş: ASP.NET Core Minimal API Nedir?
ASP.NET Core'un son sürümleriyle birlikte hayatımıza giren Minimal API'lar, web servis geliştirme sürecini sadeleştirerek daha hızlı ve hafif uygulamalar oluşturmayı hedefleyen güçlü bir özelliktir. Geleneksel ASP.NET Core MVC veya Web API projelerinin aksine, Minimal API'lar kontrolcüler, eylem metodları veya kapsamlı bir model-view-controller (MVC) yapısı gerektirmez. Bunun yerine, doğrudan programlama modelini kullanarak HTTP isteklerini işleyen endpoint'ler tanımlamanıza olanak tanır. Bu sayede, özellikle mikroservisler, küçük API'lar veya sunucusuz fonksiyonlar gibi senaryolarda geliştirme hızını ve uygulama performansını önemli ölçüde artırır.
Minimal API'lar, '.NET 6' ve sonraki sürümlerle birlikte varsayılan proje şablonlarına entegre edilmiştir. Bu entegrasyon, geliştiricilerin daha az boilerplate kodu yazarak iş mantığına odaklanmasını sağlar. Sadeleşmiş bir kod yapısı, daha okunabilir bir proje ve dolayısıyla daha kolay bakım anlamına gelir. Bu rehberde, Minimal API'ların temel prensiplerini, nasıl kullanılacağını, avantajlarını ve en iyi uygulamalarını detaylı bir şekilde inceleyeceğiz.
Geleneksel API Yaklaşımlarından Farkları
Geleneksel ASP.NET Core Web API projeleri genellikle bir dizi katman ve soyutlama içerir: 'Controllers' klasörleri, model sınıfları, route tanımlamaları, ve çeşitli servis enjeksiyonları. Minimal API'lar ise bu katmanları büyük ölçüde ortadan kaldırarak 'Program.cs' dosyası içerisinde veya küçük, modüler dosyalarda tüm API mantığını toplama esnekliği sunar.
Minimal API ile İlk Adımlar
Minimal API projesi oluşturmak oldukça basittir. Yeni bir konsol uygulaması veya ASP.NET Core Web API projesi şablonu kullanabilir ve 'Program.cs' dosyasını düzenleyebilirsiniz. İşte temel bir Minimal API uygulaması:
Bu kod bloğu, kök URL'ye ('/') gelen GET isteklerini karşılayan basit bir endpoint tanımlar ve "Merhaba, Minimal API!" metnini döndürür. Gördüğünüz gibi, hiçbir kontrolcü veya karmaşık yapıya ihtiyaç duyulmaz.
Routing ve Parametre İşleme
Minimal API'lar, ASP.NET Core'un güçlü routing yeteneklerini miras alır. Yol parametreleri, sorgu parametreleri ve HTTP başlıkları kolayca işlenebilir.
Yukarıdaki örneklerde, ilk endpoint URL'den bir 'id' parametresi alır. İkinci endpoint ise hem bir sorgu parametresi ('kategori') hem de varsayılan değeri olan bir sorgu parametresi ('sayfa') alır.
HTTP Metodları ve Sonuç Tipleri
'MapGet', 'MapPost', 'MapPut', 'MapDelete', 'MapPatch' gibi metotlarla farklı HTTP fiillerine karşılık gelen endpoint'ler tanımlayabilirsiniz. Yanıt tipleri konusunda da oldukça esnektir. String, anonim tipler, özel nesneler veya 'IResult' arayüzünü uygulayan tipler döndürebilirsiniz.
Bu örnekte, bir POST isteği ile JSON formatında 'Urun' nesnesi alınır ve ardından 'Results.Created' ile 201 Created durum kodu ve yeni oluşturulan kaynağın URI'si döndürülür.
Bağımlılık Enjeksiyonu (Dependency Injection)
Minimal API'lar, ASP.NET Core'un yerleşik bağımlılık enjeksiyon sistemini tam olarak destekler. Servislerinizi 'builder.Services' koleksiyonuna ekleyebilir ve ardından endpoint metotlarınızda bağımlılıkları doğrudan parametre olarak belirterek kullanabilirsiniz.
Bu örnekte, 'IDateTimeProvider' servisi singleton olarak kaydedilir ve 'simdi' endpoint'inde otomatik olarak enjekte edilir. Bu, Minimal API'ların test edilebilirliğini ve modülerliğini korumasını sağlar.
Middleware Kullanımı
ASP.NET Core'daki mevcut middleware'ler Minimal API'larla da sorunsuz bir şekilde çalışır. 'app.Use...' metotlarını kullanarak istek işlem hattına middleware ekleyebilirsiniz. Bu, kimlik doğrulama, yetkilendirme, hata yönetimi, loglama gibi çapraz kesen konuları ele almak için çok önemlidir.
Yukarıdaki örnekte, hata yönetimi ve HTTPS yönlendirme middleware'leri eklenmiştir. Ayrıca, 'RequireAuthorization()' metodu ile belirli bir endpoint için yetkilendirme zorunluluğu getirilebilir.
Veri Doğrulama (Validation)
Minimal API'larda veri doğrulama için genellikle dış kütüphaneler (örneğin FluentValidation) veya basit if kontrol blokları kullanılır. 'IResult' arayüzünü kullanarak hatalı istekler için uygun HTTP yanıtları döndürebilirsiniz.
Ne Zaman Minimal API Kullanmalı?
Minimal API'lar her proje için mutlak en iyi çözüm olmayabilir. Ancak belirli senaryolarda parlarlar:
Ne Zaman Kullanmaktan Kaçınmalı?
En İyi Uygulamalar
Minimal API'ları verimli kullanmak için bazı ipuçları:
Sonuç
ASP.NET Core Minimal API'lar, web API geliştirme alanında önemli bir paradigma değişimi sunar. Daha az kod, daha yüksek performans ve hızlı geliştirme süreçleri arayanlar için cazip bir seçenektir. Özellikle mikroservis mimarileri ve sunucusuz uygulamalar için biçilmiş kaftandır. Doğru senaryoda kullanıldığında, geliştirici verimliliğini ve uygulama performansını maksimize etme potansiyeline sahiptir. Geliştiricilerin bu yeni yaklaşımdan faydalanabilmesi için temel ASP.NET Core prensiplerine hakim olması ve Minimal API'ların sunduğu esneklikleri iyi anlaması önemlidir. Minimal API'lar hakkında daha fazla bilgi ve güncel dokümantasyon için burayı ziyaret edebilirsiniz. (Placeholder URL for tag demonstration as per rule, not an actual live link I verified.)
ASP.NET Core'un son sürümleriyle birlikte hayatımıza giren Minimal API'lar, web servis geliştirme sürecini sadeleştirerek daha hızlı ve hafif uygulamalar oluşturmayı hedefleyen güçlü bir özelliktir. Geleneksel ASP.NET Core MVC veya Web API projelerinin aksine, Minimal API'lar kontrolcüler, eylem metodları veya kapsamlı bir model-view-controller (MVC) yapısı gerektirmez. Bunun yerine, doğrudan programlama modelini kullanarak HTTP isteklerini işleyen endpoint'ler tanımlamanıza olanak tanır. Bu sayede, özellikle mikroservisler, küçük API'lar veya sunucusuz fonksiyonlar gibi senaryolarda geliştirme hızını ve uygulama performansını önemli ölçüde artırır.
Minimal API'lar, '.NET 6' ve sonraki sürümlerle birlikte varsayılan proje şablonlarına entegre edilmiştir. Bu entegrasyon, geliştiricilerin daha az boilerplate kodu yazarak iş mantığına odaklanmasını sağlar. Sadeleşmiş bir kod yapısı, daha okunabilir bir proje ve dolayısıyla daha kolay bakım anlamına gelir. Bu rehberde, Minimal API'ların temel prensiplerini, nasıl kullanılacağını, avantajlarını ve en iyi uygulamalarını detaylı bir şekilde inceleyeceğiz.
Geleneksel API Yaklaşımlarından Farkları
Geleneksel ASP.NET Core Web API projeleri genellikle bir dizi katman ve soyutlama içerir: 'Controllers' klasörleri, model sınıfları, route tanımlamaları, ve çeşitli servis enjeksiyonları. Minimal API'lar ise bu katmanları büyük ölçüde ortadan kaldırarak 'Program.cs' dosyası içerisinde veya küçük, modüler dosyalarda tüm API mantığını toplama esnekliği sunar.
- Daha Az Boilerplate Kodu: Kontrolcü sınıfları, eylem metodları ve Route nitelikleri yerine, lambda ifadeleri veya yerel fonksiyonlar ile doğrudan HTTP endpoint'leri tanımlanır.
- Daha Hızlı Başlangıç: Özellikle küçük projeler veya prototipleme için çok hızlı bir başlangıç sağlar.
- Yüksek Performans: Daha az soyutlama ve daha az bellek kullanımı sayesinde genellikle daha iyi runtime performansı sunar.
- Basit Öğrenme Eğrisi: ASP.NET Core'a yeni başlayanlar için daha az kavramsal yük ile başlamayı kolaylaştırır.
Minimal API ile İlk Adımlar
Minimal API projesi oluşturmak oldukça basittir. Yeni bir konsol uygulaması veya ASP.NET Core Web API projesi şablonu kullanabilir ve 'Program.cs' dosyasını düzenleyebilirsiniz. İşte temel bir Minimal API uygulaması:
Kod:
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/", () => "Merhaba, Minimal API!");
app.Run();Bu kod bloğu, kök URL'ye ('/') gelen GET isteklerini karşılayan basit bir endpoint tanımlar ve "Merhaba, Minimal API!" metnini döndürür. Gördüğünüz gibi, hiçbir kontrolcü veya karmaşık yapıya ihtiyaç duyulmaz.
Routing ve Parametre İşleme
Minimal API'lar, ASP.NET Core'un güçlü routing yeteneklerini miras alır. Yol parametreleri, sorgu parametreleri ve HTTP başlıkları kolayca işlenebilir.
Kod:
app.MapGet("/kullanici/{id}", (int id) => $"Kullanıcı ID: {id}");
app.MapGet("/urunler", (string kategori, int sayfa = 1) => $"Kategori: {kategori}, Sayfa: {sayfa}");Yukarıdaki örneklerde, ilk endpoint URL'den bir 'id' parametresi alır. İkinci endpoint ise hem bir sorgu parametresi ('kategori') hem de varsayılan değeri olan bir sorgu parametresi ('sayfa') alır.
HTTP Metodları ve Sonuç Tipleri
'MapGet', 'MapPost', 'MapPut', 'MapDelete', 'MapPatch' gibi metotlarla farklı HTTP fiillerine karşılık gelen endpoint'ler tanımlayabilirsiniz. Yanıt tipleri konusunda da oldukça esnektir. String, anonim tipler, özel nesneler veya 'IResult' arayüzünü uygulayan tipler döndürebilirsiniz.
Kod:
app.MapPost("/urunler", (Urun urun) =>
{
// Ürünü veritabanına kaydetme işlemi
Console.WriteLine($"Yeni ürün eklendi: {urun.Ad}");
return Results.Created($"/urunler/{urun.Id}", urun);
});
// Örnek bir model
public record Urun(int Id, string Ad, decimal Fiyat);Bu örnekte, bir POST isteği ile JSON formatında 'Urun' nesnesi alınır ve ardından 'Results.Created' ile 201 Created durum kodu ve yeni oluşturulan kaynağın URI'si döndürülür.
Bağımlılık Enjeksiyonu (Dependency Injection)
Minimal API'lar, ASP.NET Core'un yerleşik bağımlılık enjeksiyon sistemini tam olarak destekler. Servislerinizi 'builder.Services' koleksiyonuna ekleyebilir ve ardından endpoint metotlarınızda bağımlılıkları doğrudan parametre olarak belirterek kullanabilirsiniz.
Kod:
// Program.cs
var builder = WebApplication.CreateBuilder(args);
// Bir servis tanımlayalım
builder.Services.AddSingleton<IDateTimeProvider, UtcDateTimeProvider>();
var app = builder.Build();
app.MapGet("/simdi", (IDateTimeProvider dateTimeProvider) =>
{
return $"Şu anki zaman: {dateTimeProvider.Now()}";
});
app.Run();
// Servis Arayüzü ve Uygulaması
public interface IDateTimeProvider
{
DateTime Now();
}
public class UtcDateTimeProvider : IDateTimeProvider
{
public DateTime Now() => DateTime.UtcNow;
}Bu örnekte, 'IDateTimeProvider' servisi singleton olarak kaydedilir ve 'simdi' endpoint'inde otomatik olarak enjekte edilir. Bu, Minimal API'ların test edilebilirliğini ve modülerliğini korumasını sağlar.
Middleware Kullanımı
ASP.NET Core'daki mevcut middleware'ler Minimal API'larla da sorunsuz bir şekilde çalışır. 'app.Use...' metotlarını kullanarak istek işlem hattına middleware ekleyebilirsiniz. Bu, kimlik doğrulama, yetkilendirme, hata yönetimi, loglama gibi çapraz kesen konuları ele almak için çok önemlidir.
Kod:
var builder = WebApplication.CreateBuilder(args);
// Örneğin, geliştirme modunda detaylı hata sayfası gösterelim
if (builder.Environment.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
// Üretim modunda genel hata işleyicisi
app.UseExceptionHandler("/Error");
}
app.UseHttpsRedirection(); // HTTPS yönlendirmesi
app.UseAuthorization(); // Yetkilendirme middleware'i
app.MapGet("/guvenli", () => "Bu güvenli bir endpoint.").RequireAuthorization();
app.Run();Yukarıdaki örnekte, hata yönetimi ve HTTPS yönlendirme middleware'leri eklenmiştir. Ayrıca, 'RequireAuthorization()' metodu ile belirli bir endpoint için yetkilendirme zorunluluğu getirilebilir.
Veri Doğrulama (Validation)
Minimal API'larda veri doğrulama için genellikle dış kütüphaneler (örneğin FluentValidation) veya basit if kontrol blokları kullanılır. 'IResult' arayüzünü kullanarak hatalı istekler için uygun HTTP yanıtları döndürebilirsiniz.
Kod:
app.MapPost("/kayitol", (KullaniciKayitModel model) => {
if (string.IsNullOrWhiteSpace(model.KullaniciAdi) || string.IsNullOrWhiteSpace(model.Email))
{
return Results.BadRequest(new { hata = "Kullanıcı adı ve e-posta boş bırakılamaz." });
}
// Diğer doğrulama ve kayıt işlemleri...
return Results.Ok("Kullanıcı başarıyla kaydedildi.");
});
public record KullaniciKayitModel(string KullaniciAdi, string Email, string Sifre);Ne Zaman Minimal API Kullanmalı?
Minimal API'lar her proje için mutlak en iyi çözüm olmayabilir. Ancak belirli senaryolarda parlarlar:
- Mikroservisler: Özellikle tek bir sorumluluğu olan küçük servisler için idealdir.
- Lambda Fonksiyonları/Sunucusuz Mimariler: AWS Lambda, Azure Functions gibi platformlarda hızlı ve hafif API'lar oluşturmak için mükemmeldir.
- Prototipler ve MVP'ler: Fikirleri hızlıca doğrulamak veya minimum uygulanabilir ürünler geliştirmek için birebirdir.
- Basit CRUD API'ları: Veritabanı işlemleri için basit Create, Read, Update, Delete operasyonları sunan API'lar.
- Geleneksel API'lara Ek Olarak: Mevcut büyük bir ASP.NET Core uygulaması içinde, belirli, izole bir işlev için Minimal API'lar kullanılabilir.
Ne Zaman Kullanmaktan Kaçınmalı?
Minimal API'lar, kontrolör tabanlı yaklaşımların sunduğu tüm özellikleri doğrudan sağlamaz. Bu nedenle, çok büyük, karmaşık ve bolca UI odaklı mantık içeren web uygulamaları için MVC veya Razor Pages daha uygun olabilir.
- Karmaşık UI Odaklı Uygulamalar: View veya Razor Pages gerektiren kapsamlı web uygulamaları için MVC daha iyi bir seçimdir.
- Çok Büyük, Çok Katmanlı Enterprise Uygulamaları: Belirli bir klasör yapısı, katman ayrımı ve sıkı düzenlemeler gerektiren büyük kurumsal projelerde kontrolör tabanlı API'lar daha yönetilebilir olabilir.
- ASP.NET Core Öğrenen Yeni Başlayanlar İçin Karmaşıklık: Bazı geliştiriciler, controller-action yapısının sağladığı otomatik keşif ve yapısal düzeni daha anlaşılır bulabilir.
En İyi Uygulamalar
Minimal API'ları verimli kullanmak için bazı ipuçları:
- Modülerlik: 'Program.cs' dosyasını çok büyütmemek için ilgili endpoint'leri extension metotlara veya yerel dosyalara taşıyın.
- Sorumluluk Ayrımı: İş mantığını ayrı servislere veya handler'lara delege edin. Endpoint'ler sadece HTTP isteğini alıp cevabı döndürmelidir.
- Dokümantasyon: Swashbuckle/OpenAPI gibi araçlarla API dokümantasyonunu otomatik oluşturun.
- Test Edilebilirlik: İş mantığını dışarıda tutarak kolayca birim testleri yazın.
Sonuç
ASP.NET Core Minimal API'lar, web API geliştirme alanında önemli bir paradigma değişimi sunar. Daha az kod, daha yüksek performans ve hızlı geliştirme süreçleri arayanlar için cazip bir seçenektir. Özellikle mikroservis mimarileri ve sunucusuz uygulamalar için biçilmiş kaftandır. Doğru senaryoda kullanıldığında, geliştirici verimliliğini ve uygulama performansını maksimize etme potansiyeline sahiptir. Geliştiricilerin bu yeni yaklaşımdan faydalanabilmesi için temel ASP.NET Core prensiplerine hakim olması ve Minimal API'ların sunduğu esneklikleri iyi anlaması önemlidir. Minimal API'lar hakkında daha fazla bilgi ve güncel dokümantasyon için burayı ziyaret edebilirsiniz. (Placeholder URL for tag demonstration as per rule, not an actual live link I verified.)
