.NET 9 ile Web API'ye giriş: REST prensipleri ve neden .NET?

REST Aslında Ne Demek? İşe Oradan Başlayalım

Bir Web API yazmadan önce cevaplamamız gereken sıkıcı ama önemli bir soru var: İki bilgisayarın birbiriyle konuşması gerektiğinde ortak dil ne olacak? İşte REST tam olarak bu soruna verilmiş bir cevap. Açılımı Representational State Transfer, ama açılımını ezberlemenin kimseye faydası yok. Kafanda şöyle canlandır: Sen bir garsonsun, istemci de masadaki müşteri. Müşteri menüden bir şey istiyor, sen mutfağa gidip getiriyorsun. Müşterinin mutfağın nasıl çalıştığını bilmesine gerek yok, senin de müşterinin siparişi neden istediğini sorgulaman gerekmiyor. Aradaki tek şey net bir sipariş ve net bir teslimat.

REST bir protokol değil, bir mimari yaklaşım. Yani "şunu şöyle yapacaksın" diyen katı kurallar bütünü değil, "böyle yaparsan işler daha temiz yürür" diyen bir dizi prensip. Bu prensiplerin en önemlisi kaynak (resource) odaklı düşünmek. REST dünyasında her şey bir kaynaktır: bir kullanıcı, bir ürün, bir sipariş. Her kaynağın da bir adresi vardır ve bu adrese URL diyoruz.

Kaynak Odaklı Düşünmek Neden Önemli?

Yeni başlayanların en sık yaptığı hata, endpoint'leri eylem odaklı tasarlamak. Yani şöyle adresler üretmek:

GET  /getAllUsers
POST /createNewUser
POST /deleteUserById

Bu çalışır, ama REST mantığına aykırı. Çünkü burada URL'in kendisi bir fiil içeriyor. Oysa REST'te fiili HTTP metodu belirtir, URL sadece kaynağı işaret eder. Aynı işlemleri REST'e uygun yazarsak şöyle olur:

GET    /users        → Tüm kullanıcıları getir
POST   /users        → Yeni kullanıcı oluştur
GET    /users/42     → 42 numaralı kullanıcıyı getir
DELETE /users/42     → 42 numaralı kullanıcıyı sil

Fark ilk bakışta küçük görünüyor ama sonuçları büyük. İkinci yaklaşımda URL'e bakan herhangi bir geliştirici, ne olduğunu tahmin edebilir. /users her zaman kullanıcılarla ilgilidir; ne yapılacağını ise soldaki metot söyler. Bu tahmin edilebilirlik, bir API'yi kullanılabilir kılan şeyin ta kendisi.

REST'in Dayandığı Birkaç Temel Prensip

REST'i REST yapan birkaç temel ilke var. Bunları tek tek ezberlemene gerek yok, ama mantıklarını kavramak ileride çok işine yarayacak.

İstemci-sunucu ayrımı: İstemci arayüzle ilgilenir, sunucu veriyle. Biri değişince diğeri bozulmaz. Frontend ekibi tasarımı baştan yazsa bile senin API'n aynı çalışmaya devam eder.

Durumsuzluk (statelessness): Bu, REST'in en çok yanlış anlaşılan kısmı. Sunucu, istemcinin bir önceki isteğini hatırlamaz. Her istek, kendini anlatmak için gereken her şeyi içinde taşımak zorundadır. "Az önce giriş yapmıştım ya" diye bir şey yok; her isteğe kimlik bilgini yeniden eklersin. Bu ilk başta zahmetli gibi gelir ama sistemin ölçeklenmesini inanılmaz kolaylaştırır. Çünkü hangi sunucuya düşerse düşsün istek, o sunucunun geçmişi bilmesine gerek kalmaz.

Tek tip arayüz (uniform interface): Kaynaklara hep aynı mantıkla erişilir. Kullanıcılar için ayrı, ürünler için bambaşka bir kural seti olmaz. Öğrendiğin mantık her yerde geçerlidir.

Peki Neden .NET 9?

Bu tür bir işi yapabileceğin onlarca dil ve framework var. Node.js, Spring Boot, Django, Go... Hepsinin bir yeri var. Peki neden .NET 9? Cevabı birkaç başlıkta toplayabiliriz.

Birincisi performans. .NET, son yıllarda sessiz sedasız ama istikrarlı bir şekilde en hızlı web framework'lerinden biri haline geldi. Her yeni sürümle birlikte, sen hiçbir şey yapmadan uygulaman biraz daha hızlanıyor. .NET 9 bu çizgiyi sürdürüyor; özellikle bellek yönetimi ve başlangıç süreleri tarafında ciddi iyileştirmeler var.

İkincisi olgunluk. C# çok oturmuş, okunması keyifli bir dil. Statik tipli olması, sen kod yazarken hataların çoğunu daha çalıştırmadan yakalamanı sağlıyor. Büyük projelerde bu, saç baş yolmakla huzur içinde çalışmak arasındaki fark demek.

Üçüncüsü ekosistem. Entity Framework Core ile veritabanı işleri, yerleşik dependency injection, güçlü test altyapısı, olgun bir paket dünyası... İhtiyacın olan hemen her şey ya kutudan çıkıyor ya da bir NuGet paketi kadar uzağında. Bu seri boyunca bunların hepsine tek tek gireceğiz.

Bir API'nin Hayatında Tipik Bir İstek

Teoriyi somutlaştırmak için bir isteğin baştan sona yolculuğuna bakalım. Diyelim ki bir mobil uygulama, 42 numaralı kullanıcının bilgilerini istiyor. Şöyle bir istek gönderir:

GET /users/42 HTTP/1.1
Host: api.mertozen.com
Accept: application/json

Sunucu bu isteği alır, 42 numaralı kullanıcıyı veritabanında bulur ve şöyle bir cevap döner:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "name": "Mert Özen",
  "email": "mertozensoru@gmail.com"
}

Burada dikkat edilmesi gereken birkaç nokta var. İstek, ne istediğini net bir şekilde söyledi: GET metoduyla /users/42 kaynağını. Sunucu da cevabını iki katmanda verdi: bir durum kodu (200 OK, yani "her şey yolunda") ve asıl veri. JSON formatı ise bugün API dünyasının ortak dili; hafif, okunabilir ve neredeyse her platform tarafından anlaşılıyor. Bu ikili yapıyı, yani "durum + veri" mantığını, serinin ilerleyen yazılarında defalarca göreceğiz.

Bu Seride Neler Yapacağız?

Bu yazı, otuz yazılık bir yolculuğun ilk adımı. Buradan başlayıp sıfırdan bir Web API kuracak, sonra da onu production ortamına çıkmaya hazır hale getirene kadar her katmanını tek tek işleyeceğiz. Veritabanı bağlantısından kimlik doğrulamaya, testten Docker'a kadar. Acele etmeyeceğiz; her konuyu, neden öyle yapıldığını anlayacak kadar yavaş ele alacağız. Çünkü kodu kopyalayıp yapıştırmak kolay, ama neden öyle yazdığını bilmek seni gerçekten geliştirici yapan şey.

Bir sonraki yazıda ellerimizi kirletmeye başlıyoruz: ilk .NET 9 Web API projemizi kuracak, Program.cs dosyasının içinde ne döndüğünü satır satır anlayacağız. O zamana kadar, REST'in bu kaynak odaklı mantığını bir kenara not et; çünkü yazacağımız her şeyin temelinde bu düşünce yatıyor.