ASP.NET Core ile RESTful API Geliştirme: Kapsamlı Rehber
Modern yazılım dünyasında uygulamalar arasındaki iletişim büyük ölçüde API'ler üzerinden gerçekleşmektedir. RESTful API'ler, bu iletişimin en yaygın ve standart yöntemi olarak öne çıkmaktadır. ASP.NET Core, Microsoft'un açık kaynaklı ve platformlar arası çalışabilen framework'ü olarak RESTful API geliştirme sürecinde güçlü bir altyapı sunmaktadır.
Bu rehberde ASP.NET Core ile profesyonel düzeyde RESTful API geliştirmenin tüm aşamalarını ele alacağız. Proje kurulumundan güvenlik yapılandırmasına, performans optimizasyonundan test stratejilerine kadar geniş bir perspektif sunacağız.
REST Mimarisi ve Temel Prensipler
REST (Representational State Transfer), Roy Fielding tarafından 2000 yılında tanımlanan bir mimari stildir. RESTful API'ler bu mimari stilin prensiplerini takip eden web servisleridir. Bu prensipleri anlamak, kaliteli API tasarımının temelini oluşturur.
REST'in Altı Temel Kısıtlaması
- İstemci-Sunucu Ayrımı: İstemci ve sunucu bağımsız olarak geliştirilir ve birbirlerinin iç yapısını bilmek zorunda değildir.
- Durumsuzluk (Stateless): Her istek, sunucunun işlem yapması için gereken tüm bilgiyi içermelidir. Sunucu istemci durumunu saklamaz.
- Önbelleğe Alınabilirlik: Yanıtlar açıkça önbelleğe alınabilir veya alınamaz olarak işaretlenmelidir.
- Katmanlı Sistem: İstemci, doğrudan son sunucuya mı yoksa bir aracıya mı bağlandığını bilmek zorunda değildir.
- Tekdüze Arayüz: Kaynaklar URI'ler ile tanımlanır ve standart HTTP metotları kullanılır.
- İsteğe Bağlı Kod: Sunucu, istemciye çalıştırılabilir kod gönderebilir.
HTTP Metotları ve Kullanım Alanları
RESTful API'lerde CRUD işlemleri HTTP metotlarıyla eşleştirilir. GET metodu kaynak okuma, POST yeni kaynak oluşturma, PUT mevcut kaynağı tamamen güncelleme, PATCH kısmi güncelleme ve DELETE kaynak silme işlemleri için kullanılır. Bu metotların doğru kullanımı API tasarımının tutarlılığı açısından kritik öneme sahiptir.
ASP.NET Core Proje Kurulumu
ASP.NET Core ile RESTful API projesi oluşturmak oldukça basittir. .NET CLI kullanarak yeni bir Web API projesi oluşturabilirsiniz. Proje şablonu, Swagger entegrasyonu ve temel yapılandırma dosyalarını otomatik olarak içerir.
Proje oluşturulduktan sonra Program.cs dosyası uygulamanın giriş noktasını oluşturur. Burada servislerin kaydı, middleware pipeline yapılandırması ve uygulama ayarları gerçekleştirilir. .NET 6 ve sonrası sürümlerde minimal hosting modeli ile bu süreç daha da sadeleştirilmiştir.
Proje Yapısı ve Katmanlı Mimari
Profesyonel bir API projesi genellikle katmanlı mimari ile organize edilir. Bu yapı kodun bakımını kolaylaştırır ve test edilebilirliği artırır.
- Controllers: HTTP isteklerini karşılayan ve yanıtları döndüren katman
- Services: İş mantığının yer aldığı katman
- Repositories: Veri erişim işlemlerinin gerçekleştirildiği katman
- Models/DTOs: Veri transfer nesneleri ve entity modelleri
- Middleware: İstek-yanıt pipeline'ında çapraz kesit işlemleri
Controller Tabanlı API Geliştirme
ASP.NET Core'da geleneksel yaklaşım controller sınıfları kullanmaktır. ControllerBase sınıfından türetilen controller'lar, HTTP isteklerini karşılayan action metotları içerir. ApiController attribute'u ile donatılan controller'lar otomatik model doğrulama, otomatik HTTP 400 yanıtları ve binding source çıkarımı gibi özelliklerden yararlanır.
Route Yapılandırması
ASP.NET Core'da route yapılandırması attribute routing ile gerçekleştirilir. Controller seviyesinde tanımlanan route template, tüm action metotları için temel yolu belirler. Her action metodu kendi route segmentini ekleyebilir. Route parametreleri, kısıtlamalar ve varsayılan değerler ile esnek URL yapıları oluşturulabilir.
Action Metotları ve Dönüş Tipleri
Action metotları IActionResult veya ActionResult generic tipi döndürebilir. ActionResult tipi, hem başarılı yanıtlar hem de hata durumları için tip güvenli bir yaklaşım sunar. Ok, Created, NoContent, BadRequest ve NotFound gibi yardımcı metotlar ile uygun HTTP durum kodları döndürülür.
Controller tabanlı API geliştirmede her endpoint'in tek bir sorumluluk ilkesine uyması, kodun okunabilirliğini ve bakımını önemli ölçüde artırır.
Minimal API Yaklaşımı
ASP.NET Core 6 ile tanıtılan Minimal API'ler, daha az kod ile hızlı API geliştirme imkanı sunar. Controller sınıflarına ihtiyaç duymadan doğrudan endpoint tanımlamaları yapılabilir. Bu yaklaşım özellikle mikro servisler ve küçük ölçekli API'ler için idealdir.
Minimal API'lerde endpoint'ler doğrudan Program.cs dosyasında veya extension metotları aracılığıyla tanımlanır. Map metotları (MapGet, MapPost, MapPut, MapDelete) ile HTTP metotlarına karşılık gelen handler fonksiyonları belirlenir. Route grupları ile ortak yapılandırmalar merkezi olarak yönetilebilir.
Minimal API ile Controller Karşılaştırması
Her iki yaklaşımın avantajları ve dezavantajları bulunmaktadır. Controller tabanlı yaklaşım büyük projeler için daha uygunken, Minimal API'ler küçük ve orta ölçekli projeler ile prototipleme için daha verimlidir. .NET 7 ve sonrası sürümlerde Minimal API'lere eklenen filtre desteği, grup yapılandırması ve endpoint metadata özellikleri bu yaklaşımı daha da güçlendirmiştir.
Veri Doğrulama (Validation)
API'lerde gelen verilerin doğrulanması güvenlik ve veri bütünlüğü açısından kritik öneme sahiptir. ASP.NET Core, Data Annotations ve FluentValidation gibi doğrulama mekanizmaları sunar.
Data Annotations ile Doğrulama
Model sınıflarına eklenen attribute'lar ile basit doğrulama kuralları tanımlanabilir. Required, StringLength, Range, RegularExpression ve Compare gibi yerleşik attribute'lar yaygın doğrulama senaryolarını karşılar. ApiController attribute'u ile birlikte geçersiz model durumunda otomatik olarak HTTP 400 yanıtı döndürülür.
FluentValidation Entegrasyonu
Daha karmaşık doğrulama senaryoları için FluentValidation kütüphanesi tercih edilebilir. Bu kütüphane ile doğrulama kuralları model sınıflarından ayrı tutulur ve daha okunabilir bir sözdizimi ile tanımlanır. Koşullu doğrulama, özel doğrulama kuralları ve hata mesajı özelleştirme gibi gelişmiş özellikler sunar.
Kimlik Doğrulama ve Yetkilendirme
API güvenliği modern uygulama geliştirmenin en önemli konularından biridir. ASP.NET Core, JWT (JSON Web Token) tabanlı kimlik doğrulama, OAuth 2.0 ve OpenID Connect protokollerini destekler.
JWT Tabanlı Kimlik Doğrulama
JWT, API güvenliğinde en yaygın kullanılan yöntemdir. Kullanıcı giriş yaptığında sunucu bir JWT token oluşturur ve istemciye döndürür. İstemci sonraki isteklerde bu token'ı Authorization header'ında gönderir. Sunucu token'ı doğrulayarak kullanıcının kimliğini ve yetkilerini belirler.
Token yapılandırmasında issuer, audience, signing key ve token süresi gibi parametreler belirlenir. Refresh token mekanizması ile kullanıcı deneyimi iyileştirilirken güvenlik seviyesi korunur.
Yetkilendirme Politikaları
ASP.NET Core'da yetkilendirme, roller ve politikalar aracılığıyla yönetilir. Authorize attribute'u ile controller veya action seviyesinde erişim kısıtlamaları tanımlanır. Politika tabanlı yetkilendirme ile daha esnek ve karmaşık yetkilendirme senaryoları uygulanabilir.
API güvenliğinde katmanlı bir yaklaşım benimseyin. Kimlik doğrulama, yetkilendirme, rate limiting ve input validation birlikte kullanılmalıdır.
Hata Yönetimi ve Loglama
Profesyonel bir API'de hata yönetimi tutarlı ve bilgilendirici olmalıdır. ASP.NET Core, global exception handling middleware ile merkezi hata yönetimi imkanı sunar. ProblemDetails standardı (RFC 7807) ile hata yanıtları yapılandırılmış bir formatta döndürülür.
Global Exception Handler
Middleware pipeline'ına eklenen exception handler, yakalanmamış hataları merkezi olarak ele alır. Geliştirme ortamında detaylı hata bilgisi döndürülürken, üretim ortamında güvenlik açısından genel hata mesajları kullanılır. Serilog veya NLog gibi kütüphaneler ile yapılandırılmış loglama gerçekleştirilir.
Özel Hata Sınıfları
İş mantığına özgü hata durumları için özel exception sınıfları oluşturulabilir. NotFoundException, ValidationException ve BusinessRuleException gibi sınıflar ile hata türleri açıkça tanımlanır ve uygun HTTP durum kodları ile eşleştirilir.
Performans Optimizasyonu
API performansı kullanıcı deneyimini doğrudan etkiler. ASP.NET Core, yüksek performanslı bir framework olarak birçok optimizasyon imkanı sunar.
- Response Caching: Sık değişmeyen yanıtlar önbelleğe alınarak sunucu yükü azaltılır.
- Asenkron Programlama: async/await kullanımı ile thread havuzu verimli kullanılır.
- Sayfalama (Pagination): Büyük veri setleri sayfalanarak aktarılır.
- Sıkıştırma: Response compression middleware ile yanıt boyutu küçültülür.
- Rate Limiting: .NET 7 ile gelen yerleşik rate limiting middleware ile API kullanımı kontrol altına alınır.
- Output Caching: .NET 7 ile tanıtılan output caching middleware ile sunucu tarafında yanıt önbellekleme yapılır.
API Versiyonlama
API'ler zamanla değişir ve gelişir. Mevcut istemcileri bozmadan yeni özellikler eklemek için versiyonlama stratejisi belirlenmelidir. ASP.NET Core'da URL tabanlı, header tabanlı ve query string tabanlı versiyonlama yöntemleri desteklenir.
Asp.Versioning.Http paketi ile versiyonlama altyapısı kolayca entegre edilir. Deprecated versiyonların yönetimi, varsayılan versiyon belirleme ve versiyon raporlama gibi özellikler bu paketle birlikte gelir.
API Dokümantasyonu
İyi dokümante edilmiş bir API, geliştiricilerin entegrasyon sürecini önemli ölçüde kolaylaştırır. ASP.NET Core'da Swagger/OpenAPI entegrasyonu Swashbuckle veya NSwag paketleri ile sağlanır. .NET 9 ile birlikte Microsoft.AspNetCore.OpenApi paketi yerleşik olarak sunulmaktadır.
XML yorumları ile action metotları ve model sınıfları dokümante edilir. Swagger UI üzerinden interaktif API testi yapılabilir. Ayrıca Scalar gibi modern dokümantasyon araçları da ASP.NET Core ile kolayca entegre edilebilir.
Test Stratejileri
API'lerin güvenilirliğini sağlamak için kapsamlı test stratejisi uygulanmalıdır. Unit testler iş mantığını, entegrasyon testleri API endpoint'lerini ve uçtan uca testler tüm sistemi doğrular.
Entegrasyon Testleri
WebApplicationFactory sınıfı ile bellek içi test sunucusu oluşturularak API endpoint'leri gerçekçi koşullarda test edilir. HttpClient ile istekler gönderilir ve yanıtlar doğrulanır. Bu yaklaşım veritabanı bağımlılıklarını mock'lamaya veya test veritabanı kullanmaya olanak tanır.
Sonuç ve Öneriler
ASP.NET Core ile RESTful API geliştirme, doğru mimari kararlar ve best practices ile son derece verimli bir süreçtir. Katmanlı mimari, güçlü doğrulama, kapsamlı güvenlik ve performans optimizasyonları ile profesyonel düzeyde API'ler oluşturulabilir.
Başarılı bir API geliştirme süreci için REST prensiplerini anlamak, ASP.NET Core özelliklerini etkin kullanmak ve sürekli öğrenmeye açık olmak gerekmektedir. Microsoft'un düzenli olarak yayınladığı güncellemeler ve topluluk katkıları ile ASP.NET Core ekosistemi sürekli gelişmektedir.
Projelerinizde bu rehberde ele aldığımız konuları uygulayarak güvenli, performanslı ve sürdürülebilir API'ler geliştirebilirsiniz. Her zaman kod kalitesini ön planda tutun, testlerinizi yazın ve dokümantasyonunuzu güncel tutun.
