Data API Builder 2.0: REST Yolunu İş Yapına Göre Kurmak
Şöyle bir sahne düşünün: ekipteki backend geliştirici, veritabanındaki 40 küsür tabloyu REST olarak açmak istiyor. Önünde iki yol var. Ya her endpoint için controller yazacak, filtreleme, sayfalama, caching derken işi elle örmeye devam edecek, ya da Data API builder gibi bir motor kurup birkaç satır YAML ile aynı kapıyı aralayacak.
Ne yalan söyleyeyim, Ben açıkçası ikinci taraftayım. Ama DAB 2.0 gelmeden önce bu yolun can sıkıcı bir eksiği vardı: endpoint yapısı düz ve tek katmandı. Yanı /api/Customer, /api/Order, /api/Invoice… hepsi aynı seviyede duruyordu. İş tarafında bunları gruplayayım deseniz — mesela iç kullanım, dış kullanım, finans, raporlama diye — elinizde pek oynayacak bir araç yoktu.
Kısa bir not düşeyim buraya.
Size bir şey söyleyeyim, Mayıs 2024’te preview çıkıp Haziran’da GA olunca iş değişti. Şimdi endpoint yolunu istediğiniz gibi compound path olarak kurabiliyorsunuz. Küçük bir detay gibi dürüyor, biliyorum. Ama işin aslı şu: API yüzeyinizi veritabanı topolojinize değil, iş yapınıza göre şekillendirmenizi sağlıyor (şaşırtıcı ama gerçek). Bunlar aynı şey değil.
DAB Kısaca Ne Yapıyor?
Aslında, Bilmeyenler için üç cümlede toparlayayım. Data API builder, üretimdeki SQL veritabanınızı (Azure SQL, SQL Server, PostgreSQL, MySQL, Cosmos DB) REST, GraphQL. MCP olarak dışarı açmanıza yarayan açık kaynaklı bir motor. Docker imajı olarak da koşuyor,.NET tool olarak da çalışıyor (ben de ilk duyduğumda şaşırmıştım). Konfigürasyonu tek bir JSON dosyasından yönetiyorsunuz.
Kutudan çıktığı hâliyle size şunları veriyor: sayfalama, filtreleme (OData tarzı sözdizimi ile), projection, önbellek, throttling. Satır seviyesinde yetkilendirme. Yanı normalde bir REST API için ekibin haftalarca uğraşacağı boilerplate işi — paketlenmiş hâlde geliyor.
Kurumsal projelerde sık gördüğüm senaryo şu: read-heavy bir iç panel yazılacak, backend ekibi zaten dolu. Tabloları güvenli şekilde okutmak lazım. DAB tam bu boşluğa oturuyor. Yazmadığınız her satır, bakmadığınız her bug demek. Bence bu taraf biraz hafife alınıyor.
Evet.
Endpoint Yolu Nasıl Kuruluyor?
Bir REST yolu DAB tarafında üç parçadan oluşuyor:
- Host adı — localhost olabilir, Azure Container Apps domain’i olabilir, App Service olabilir; neyse artık.
- Global runtime prefix —
runtime.rest.path, varsayılan değer de/api. - Entity yolu — işte 2.0 ile esnekleşen kısım burası.
Şunu fark ettim: Peki neden? Çünkü 2.0 öncesinde entity yolu tek segment olmak zorundaydı (ki bu çoğu kişinin gözünden kaçıyor). Yanı /Customer yazabiliyordunuz. /external/v2/customers yazamıyordunuz; denerseniz motor kabul etmiyordu. Şimdi işe istediğiniz kadar alt segment ekleyebiliyorsunuz ve burada oyun baya değişiyor.
En Basit Hali
Aşağıdaki config ile Customer tablonuz doğrudan /api/Customer altında çıkıyor. Standart senaryo bu; çoğu proje de zaten buradan başlıyor:
{
"runtime": {
"rest": {
"enabled": true,
"path": "/api"
}
},
"entities": {
"Customer": {
"source": {
"object": "dbo.Customer",
"type": "table"
},
"rest": {
"enabled": true,
"path": "/Customer"
}
}
}
}Sonuç: https://localhost/api/Customer. Fena değil yanı; iş görüyor. Ama beş on entity’niz olunca hepsi aynı yere yığılmaya başlıyor ve yüzey biraz karışıklaşıyor.
Compound Path ile Gruplamak
Sıradaki kısım daha hoş dürüyor aslında. Entity path’ine slash koyarak istediğiniz kadar alt segment ekleyebiliyorsunuz:
"entities": {
"Customer": {
"rest": { "path": "/external/v2/Customer" }
},
"Invoice": {
"rest": { "path": "/finance/Invoice" }
},
"AuditLog": {
"rest": { "path": "/internal/audit/AuditLog" }
}
}Böylece dışa açık uç noktalarla finans tarafındakilerle iç kullanımdakiler net biçimde ayrılıyor. API tüketen tarafın kafası daha az karışıyor, dokümantasyon da daha okunur oluyor (garip ama doğru). Gateway seviyesinde politika uygulaması da kolaylaşıyor çünkü /internal/* altındakileri büyük ölçüde dış trafikten kesebilirsiniz.
Neden Bu Küçük Değişiklik Büyük Fark Yaratıyor?
Bi saniye — Bak şimdi mesele şu: veritabanı topolojisi ile iş domain’i çoğu zaman örtüşmüyor bile demeyeyim; bazen birbirinden epey uzak kalıyorlar. Veritabanında tablo yapınız normalize edilmiş oluyor, join’lerle besleniyor. Tarihsel sebeplerle isimlendirilmiş olabiliyor. Ama API tüketen ekipler bu iç yapıyla ilgilenmiyor ki; onlar müşteriyle siparişle faturayla düşünüyor.
dbo.tbl_cust_master_v2 olabilir — kimin umurunda gerçekten? Dışarıda bunu sadece daha anlaşılır bir yola bağlayın: mesela /api/crm/customers olsun, kullanıcı da rahat etsin.
API yüzeyi bir ürün gibi tasarlanmalı. Veritabanı işe iç mesele olarak kalmalı. DAB
Bu ayrımı nihayet mümkün kılıyor ; bunu kağıt üstü ideal olmaktan çıkarıp konfigürasyona indiriyor.
Versiyonlama Meselesi
Bir de şu var : API versiyonlaması. Kimse
/ api / v1 / Customer
ile
/ api / v2 / Customer
arasındaki farkı manuel controller yazmadan çözmek istemez mi ? İstiyoruz tabi. Compound path ile aynı tabloyu farklı yollarla, farklı yetkilendirme kurallarıyla, hatta farklı alan seçimleriyle ( field-level auth ) yayınlayabiliyorsunuz (evet, doğru duydunuz).
Şöyle bir yapı düşünün :
{
"Customer_v1":
{
"source":
{
"object":"dbo.Customer",
"type":"table"
},
"rest":
{
"path":"\/v1\/Customer"
}
},
"Customer_v2":
{
"source":
{
"object":"dbo.Customer",
"type":"table"
},
"rest":
{
"path":"\/v2\/Customer"
},
"mappings":
{
"cust_email":"emailAddress",
"cust_name":"fullName"
}
}
} v1 eski isimlendirmeyi koruyor, v2 işe biraz daha temiz alan adları sunuyor. Aynı tablo, iki farklı yüzey. Migration dönemlerinde bu esneklik altın değerinde oluyor, şaşırdım açıkçası.
Tam da öyle.
Türkiye’deki Kurumsal Ekipler Açısından Değerlendirme
Sahada gözlemlediğim kadarıyla Türkiye’deki orta. Büyük ölçekli şirketlerde REST API tasarımı hâlâ “controller yazmak” ile eş anlamlı görülüyor.
DAB gibi düşük kod motorlarıysa çoğu yerde biraz önyargıyla karşılanabiliyor — “biz bunu kendimiz yazalım,
kontrolü kaybetmeyelim” refleksi kuvvetli oluyor.
Peki neden?
Çünkü alışkanlık kolay bozulmuyor.
Ama bazen alışkanlık dediğimiz şey,
sadece eski yorgunlukların tekrar etmesi oluyor.
Kısa bir not düşeyim buraya.
Oysa iş gerçeği başka.
Ekipler dolu,
backlog kabarmış,
yeni feature’lar sıraya girmiş durumda.
Bu koşullarda
40 tablo için
40 controller,
40 test suite,
40 dokümantasyon üretmek ciddi israf.
Hele iç panellerde,
admin araçlarında,
raporlama tarafında bu daha da belirginleşiyor.
DAB burada haftalar kazandırabiliyor ;
bunu küçümsememek lazım.
Neyse,
çok dağıttım,
konumuza dönelim.
Bakın, Bir uyarı da bırakayım :
DAB her senaryonun ilacı değil.
Karmaşık iş kuralları içeren,
birden fazla tabloyu tek işlemde güncelleyen,
çok özel authorization mantığı barındıran endpoint’ler için hâlâ elle yazılmış API katmanı daha uygun kalıyor.
DAB’ı CRUD ağırlıklı okuma senaryolarında düşünün ;
orada baya iş görüyor.
İşin aslı bu kadar basit.
Küçük Ekip mi,
Büyük Kurumsal Yapı mı?
Küçük bir startup’sanız ya da
3-5 kişilik bir ekipseniz:
DAB’ı
runtime.rest.path
altında düz bir yapıyla başlatın.
Erken optimizasyon yapmayın.
İhtiyaç doğduğunda compound path’e geçersiniz;
config değişikliği zaten dakikalar sürüyor.
Bazen en doğrusu budur,
fazla akıllılık etmeye gerek yok.
E sonra?
Sonra büyüdüğünüzde zaten yeniden düzenlersiniz.
Bence, Enterprise seviyesindeyseniz durum biraz değişiyor.
En baştan bir API taxonomy’si oturtmanızı öneriyorum:
/ public,
/ internal,
/ partner,
/ admin
gibi ana gruplar;
altlarında iş domain’leri olsun.
Bu yapıyı APIM (Azure API Management) tarafında da aynı şekilde yansıtın.
Böylece gateway policy’leri,
subscription key’ler ve rate limit’ler mantıklı bir çizgide ilerliyor.
Her şeyi sonradan yamamak yerine baştan sade tutmak daha az yorucu oluyor ;
garip ama gerçek.
İlk Adımlar”
Denenek isteyenler için hızlıca yol haritasını bırakayım: (şaşırtıcı ama gerçek)
>
Sıkça Sorulan Sorular
Data API builder ücretsiz mi?
Evet, DAB açık kaynaklı ve MIT lisansıyla dağıtılıyor. Yanı motor için tek kuruş ödemiyorsunuz. Ödediğiniz tek şey aslında nerede koşturduğunuz — Azure Container Apps, App Service ya da kendi Kubernetes cluster’ınızın maliyeti. Lisans derdi yok.
Compound path performansı etkiliyor mu?
Ölçülebilir bir etki görmüyorsunuz. Path parsing hani çok erken bir aşamada bir kez yapılıyor, sonrası aynı pipeline üzerinden gidiyor. Tecrübeme göre kısa path ile uzun path arasında pratikte hissedilir bir gecikme farkı yok (eh, fena değil). Asıl performans meselesi DAB’ın veritabanı sorgu üretme katmanında belirleniyor (ben de ilk duyduğumda şaşırmıştım)
DAB’ı REST için mi GraphQL için mi kullanmalıyım?
Aslında ikisini birden kullanabilirsiniz. Aynı motor, aynı config üzerinden her ikisini de üretiyor. REST’in araç desteği daha yaygın, öğrenme eğrisi de düşük. Ama mesela nested sorgu ve field selection ihtiyacınız varsa GraphQL çok daha güçlü. Aynı entity’yi hem /api/Customer olarak REST’te hem de GraphQL şemasında görebiliyorsunuz — bence bu oldukça kullanışlı.
Production’da güvenli mi?
Genel olarak evet. Ama authorization ayarlarına dikkat edin, açıkçası bu kısım gözden kaçabiliyor. Varsayılan olarak anonymous rolü hiçbir şeye erişemiyor, yanı başlangıç noktası güvenli. Bununla birlikte config’te yanlışlıkla açık bırakılan bir permission tüm tabloyu dışarı verebiliyor. CI/CD’ye config lint aşaması ekleyin, kod review’da da bu dosyayı ayrıca gözden geçirin.
Mevcut projelerimde 1.x’ten 2.0’a geçmek zor mu?
Bunu yaşayan biri olarak söyleyeyim, Zor değil, tecrübeme göre oldukça pürüzsüz geçiyor. Config şeması geriye dönük uyumlu — yanı mevcut config dosyanız 2.0’da da çalışıyor. Compound path’i hani sadece istediğiniz entity’lerde kullanmaya başlayabilirsiniz, hepsini tek seferde değiştirmek zorunda değilsiniz. Test ortamında bir hafta koşturup sonra production’a alın.
Kaynaklar ve İleri Okuma
20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.
2 comments