ASP.NET Core ile İlk Web API Projesi Nasıl Oluşturulur?

ASP.NET Core ile İlk Web API Projesi Nasıl Oluşturulur? Doğrulanmış bir Web API şablonuyla proje oluşturabilir, başlangıç dosyasında bellekteki ders görevlerini döndüren bir GET endpoint'i tanımlayabilir ve uygulamanın yerel adreste verdiği yanıtı test edebilirsin. En küçük çalışan örnek için minimal API yaklaşımı, başlangıç akışını birkaç temel dosyada görmeni sağlar.

İlk adımda uygun SDK ve proje şablonunu seçmek, ardından dosyaların görevini ayırmaktır. Böylece Program.cs içindeki uygulama oluşturma ve endpoint kaydı ile yerel çalıştırma ayarlarını birbirine karıştırmadan ilerleyebilirsin.

ASP.NET Core Web API projesi için hangi hazırlıklar gerekir?

Başlangıç için C# ile değişkenleri, koleksiyonları, sınıfları veya record türlerini ve temel metot çağrılarını okuyabilmen işini kolaylaştırır. HTTP yöntemi, URL yolu ve JSON arasındaki ilişkiyi bilmek de faydalıdır. C# düzeyini ölçmek istersen C# bilgi testini çözebilirsin.

Makinede geliştirme için.NET SDK kurulu olmalıdır. Microsoft'un Minimal API belgeleri.NET 10 SDK'yı ön koşul olarak listeler ve destek politikasında.NET 10 aktif LTS sürümü olarak yer alır. Visual Studio kullanıyorsan ASP.NET ve web geliştirme iş yükünü, Visual Studio Code kullanıyorsan C# Dev Kit'i hazır bulundur. Şablon seçeneklerinin ayrıntılarını Microsoft Learn'deki.NET varsayılan şablonları sayfasında görebilirsin.

webapi kısa adı ASP.NET Core Web API şablonunu, --use-minimal-apis seçeneği minimal API yaklaşımını, --framework net10.0 ise hedef frameworkü açıkça belirtir. Projeyi DersApi adıyla oluşturup çalıştırmak için şu sırayı kullan:

dotnet new webapi --use-minimal-apis --framework net10.0 -o DersApi
cd DersApi
dotnet run

dotnet new proje dosyalarını oluşturur, -o DersApi çıktıyı bu klasöre verir. cd proje klasörüne geçer, dotnet run uygulamayı yerel geliştirme için başlatır. Terminalde gösterilen yerel adresi sonraki testte kullan; port numarasını önceden varsayma.

İlk Web API projesinin dosyaları ne işe yarar?

Şablonun ürettiği Program.cs dosyasında başlangıç akışını şu sırayla okuyabilirsin: WebApplication.CreateBuilder(args) yapılandırılmış bir builder oluşturur, builder.Build() uygulamayı üretir, app.MapGet(...) gibi kayıtlar uygulama oluşturulduktan sonra eklenir ve app.Run() uygulamayı çalıştırır. Ders görevlerini döndüren endpoint de bu akışta, app.Run() çağrısından önce tanımlanır. Bu başlangıç modeli hakkında ayrıntı için Microsoft Learn'deki WebApplication açıklamasını inceleyebilirsin.

Dosya akışını birlikte okuduğunda .csproj projenin hedefini ve bağımlılıklarını tanımlar, Program.cs uygulamayı kurup endpoint'i kaydeder, launchSettings.json ise yerel çalıştırma sırasında adres ve ortam ayarlarını sağlar.

Bellekteki ders görevlerini döndüren GET endpoint nasıl yazılır?

İlk GET endpointi için önce uygulamayı oluşturup bellekte iki görev tanımlayabilir, ardından belirli bir URL yolunu bu görevleri döndüren işleyiciye bağlayabilirsin. Aşağıdaki örnek, başlangıç dosyasına eklenebilecek kısa ve çalışır bir Minimal API örneğidir.

Çalışan mini örnek

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

var gorevler = new[] { new { id = 1, title = "GET endpointini çalıştır", completed = false }, new { id = 2, title = "JSON yanıtını incele", completed = false } };

app.MapGet("/api/ders-gorevleri", () => Results.Ok(gorevler));

app.Run();

WebApplication.CreateBuilder(args) uygulamanın hazırlık aşamasını başlatır. builder.Build() sonrasında oluşan app nesnesi üzerine endpoint kaydı yapılır. MapGet çağrısında ilk bölüm, GET isteğinin eşleşeceği URL yolunu belirtir. İkinci bölümdeki lambda işleyicisi, eşleşme gerçekleştiğinde çalışır. app.Run() satırı ise endpoint kaydından sonra uygulamayı çalıştırır.

gorevler dizisi yalnızca uygulamanın belleğinde tutulur. Results.Ok(gorevler) bu diziyi başarılı bir HTTP yanıtının gövdesi olarak döndürür. Bu yanıtın durum kodu 200 OK olur ve gövde JSON biçiminde sunulur.

Okunabilir biçimde beklenen JSON gövdesi şöyledir:

[
  {
    "id": 1,
    "title": "GET endpointini çalıştır",
    "completed": false
  },
  {
    "id": 2,
    "title": "JSON yanıtını incele",
    "completed": false
  }
]

Buradaki veri kaynağı harici bir kalıcı sistem değil, uygulama belleğindeki dizidir. Uygulama yeniden başlatıldığında bu dizi kodda belirtilen başlangıç değerleriyle yeniden oluşturulur. Bu nedenle örnek, veri saklama işlemini değil, bir GET endpointinin istek karşılığında veri döndürme akışını göstermek için kullanılır.

GET isteği JSON yanıtına nasıl dönüşür?

/api/ders-gorevleri ifadesi route, yani belirli bir HTTP yöntemiyle gelen isteğin eşleşeceği URL kuralıdır. Endpoint işleyicisi ise bu eşleşme gerçekleştiğinde çalışan ve yanıtı oluşturan lambda ifadesidir. Kısaca route hangi isteğin seçileceğini, işleyici ise seçilen isteğe hangi verinin döndürüleceğini belirler. Minimal API'de route handler, route eşleştiğinde çalışır; işleyicinin döndürdüğü sonuç HTTP yanıtına dönüştürülür.

1. GET isteğini gönder: /api/ders-gorevleri adresine bir GET isteği gönder. Beklenen gözlem: Uygulama, bu yol ve yöntemle gelen isteği işlemeye başlar.
2. Route eşleşmesini gözlemle: İstek yöntemi GET ve URL yolu /api/ders-gorevleri olduğu için kayıtlı route ile karşılaştırılır. Beklenen gözlem: İstek, ders görevlerini döndüren endpoint ile eşleşir.
3. Bellekteki veriyi oku: Eşleşen endpoint işleyicisi, uygulama belleğinde bulunan gorevler dizisine erişir. Beklenen gözlem: İki görev nesnesi, id değerleri ve başlıklarıyla birlikte işleme alınır.
4. Başarılı yanıtı oluştur: İşleyici, diziyi Results.Ok sonucunun içine yerleştirir. Beklenen gözlem: Yanıtın durum kodu 200 OK olarak hazırlanır.
5. Gövdeyi ve durum kodunu karşılaştır: Dönen yanıtın durum kodunu ve gövdesini birlikte incele. Beklenen gözlem: Durum kodu 200 olur, gövde ise iki nesneli JSON dizi olarak ve application/json içerik türüyle sunulur.

Bu akışta durum kodu isteğin sonucunu, JSON gövdesi ise dönen verinin içeriğini anlatır. İkisini birlikte kontrol etmek, endpointin yalnızca eşleştiğini değil, beklenen veriyi doğru yanıt biçimiyle sunduğunu anlamanı sağlar.

İlk GET endpoint nasıl çalıştırılır ve test edilir?

Proje klasöründe bir terminal aç ve uygulamayı başlat:

dotnet run

dotnet run projeyi derleyerek çalıştırır. Başlatma ayarları kullanılıyorsa yerel adres seçilen profilden gelir. Bu nedenle örnek bir portu kopyalamak yerine terminaldeki Now listening on: satırında gösterilen adresi esas al. Properties/launchSettings.json içinde https adlı profil bulunuyorsa bu profili açıkça seçmek için dotnet run --launch-profile https komutunu kullanabilirsin.

Yerel HTTPS adresinde sertifika uyarısıyla karşılaşırsan geliştirme sertifikasını oluşturmak veya güvenilir hâle getirmek için şu komutu çalıştırabilirsin:

dotnet dev-certs https --trust

İşletim sistemi ya da tarayıcı sertifika işleminden sonra yeniden başlatma veya ek onay isteyebilir. Bu sertifika yalnızca yerel geliştirme sürecinde HTTPS kullanımı içindir.

1. Now listening on: satırındaki adresi http veya https bölümü ve portuyla birlikte kopyala.
2. Adresin sonuna /api/ders-gorevleri yolunu ekleyip oluşan adresi tarayıcıda aç. Adres çubuğundan yapılan bu istek bir GET isteğidir.
3. Sayfada, önceki bölümde tanımladığın ders görevlerinden oluşan JSON dizisinin görüntülendiğini kontrol et.
4. Tarayıcının geliştirici araçlarındaki Ağ panelini açıp sayfayı yenile. İsteği seçerek durum kodunun 200, yanıt gövdesinin beklenen JSON ve içerik türünün application/json olduğunu doğrula.

Yanıt gelmezse hangi sırayla kontrol etmelisin?

• Uygulama başlamıyorsa: Terminaldeki derleme çıktısında görünen ilk hatayı incele. Dosya adı ve satır bilgisi genellikle kontrol etmen gereken Program.cs bölümünü gösterir.
• 404 Not Found alıyorsan: MapGet içinde tanımlanan route ile tarayıcıdaki /api/ders-gorevleri yolunu karakter karakter karşılaştır.
• Bağlantı kurulamıyorsa: Uygulamanın çalışmaya devam ettiğini ve terminalde en son gösterilen adresi kullandığını doğrula. Eski port veya http ile https karışıklığı bağlantıyı engelleyebilir.
• JSON beklediğinden farklıysa: Endpoint işleyicisinin döndürdüğü koleksiyonu ve görev nesnelerinin özelliklerini yeniden kontrol et.

Kurulum ve ilk endpoint için dört maddelik kontrol listesi

Bir nesne veya koleksiyon döndüren Minimal API işleyicisi, başarılı istekte veriyi JSON olarak serileştirerek 200 OK yanıtı üretebilir. Böylece kontrol yalnızca ekranda veri görmeye değil, yanıt biçimi ile durum kodunu birlikte doğrulamaya dayanır.

• SDK ve şablon: Proje dosyasındaki hedef çerçevenin kurulu SDK ile uyumlu olduğunu dotnet --info çıktısından doğruladın ve projeyi ASP.NET Core Web API şablonuyla oluşturdun.
• Derleme ve başlangıç: Program.cs hatasız derleniyor, dotnet run uygulamayı başlatıyor ve terminal yerel dinleme adresini gösteriyor.
• Adres ve route: Terminaldeki güncel yerel adres ile /api/ders-gorevleri yolunu doğru biçimde birleştirdin.
• GET yanıtı: Tarayıcı isteği beklenen ders görevleri JSON’unu döndürüyor ve Ağ panelinde 200 OK durum kodu görülüyor.

Yazılım alanındaki ilgi yönünü farklı başlıklar üzerinden değerlendirmek istersen ücretsiz kariyer testinden yararlanabilirsin.

Bu kontroller tamamlandığında ilk GET endpointin çalışıyor, doğru route üzerinden erişiliyor ve ürettiği HTTP yanıtı temel düzeyde doğrulanmış olur.