Kompozit API’lerle Mikroservislerde Veriyi Tek Noktadan Sunmak

Giriş: Mikroservislerde dağınık veri problemi

Mikroservis yaklaşımı; ekiplerin bağımsız geliştirme/deploy, ölçeklenebilirlik ve domain ayrışması gibi önemli kazanımlar sağlar. Ancak bu model, basit bir ekranı bile beslemek için çoğu zaman birden fazla servise istek atmayı gerektirir. Bu da tarayıcı tarafında fazladan gecikme, gereksiz karmaşıklık ve kullanıcı deneyiminde tutarsızlık demektir.

İşte tam bu noktada kompozit API (composite/aggregation) yaklaşımı devreye girer: Birden fazla servis çağrısını arka planda birleştirip istemciye tek bir cevap döner.

Kompozit API nedir?

Kompozit API, farklı mikroservislerden gelen yanıtları tek bir kompozit uç noktada birleştirerek istemciye bütünleşik bir veri modeli sunar. İstemcinin ağ üstünden 3–5 istek atması (round-trip) yerine tek bir istekte bulunmasını sağlar. Bu uç nokta, bir gateway üzerinde, ayrı bir aggregation service içinde veya ilgili bounded context’in “composite” controller’ında yer alabilir.

Neden ihtiyaç duyarız?

• Performans: Tek istek → daha az round-trip, daha hızlı ilk boyama ve etkileşim.
• Sadelik: Frontend kodunda daha az istek yönetimi, daha basit durum (state) akışı.
• Tutarlılık: Aynı ekranda gösterilen ilişkili verilerin tek yerde kural/filtre uygulanarak döndürülmesi.
• Merkezi hata yönetimi: Zaman aşımı, retry, fallback gibi politikaları birleştirme katmanında kontrol etmek.

Örnek senaryo: Kullanıcı ekleme ekranında rol + departman verileri

Bir yönetim panelinde “Kullanıcı Ekle” ekranını düşünün. Ekranda rol seçimi (checkbox) ve departman seçimi (dropdown) aynı formda yer alıyor. Tipik mikroservis düzeninde bu veriler iki farklı servisten gelir:

• RoleService → Tüm aktif roller
• DepartmentService → Tüm aktif departmanlar

UI’nin iki ayrı istek atması yerine, tek bir kompozit uç nokta tanımlarız:

GET /api/v1/composite/rolesanddepartments

Bu uç nokta arka planda rol ve departman servislerini çağırır, veriyi filtreler/normalize eder ve tek DTO ile cevap döner:

{
  "roles": [
    { "id": "7f2e...", "name": "Admin" },
    { "id": "2b9a...", "name": "Editor" },
    { "id": "6c31...", "name": "Viewer" }
  ],
  "departments": [
    { "id": "a110...", "name": "Satış" },
    { "id": "b221...", "name": "İnsan Kaynakları" },
    { "id": "c332...", "name": "Operasyon" }
  ]
}

Frontend tarafında bu tek yanıtla hem rol checkbox’ları hem de departman seçimi aynı anda doldurulur. Form açılış süresi kısalır, gereksiz istek yönetimi kodu ortadan kalkar.

Kompozit API’yi nerede konumlandırmalı?

• API Gateway üzerinde: Kuralların merkezi yönetimi, rate limit, circuit breaker, cache.
• Aggregation Service olarak ayrık bir servis: Tek sorumluluk, yatay ölçekleme esnekliği.
• Domain controller içinde “composite” alanı: Küçük ekiplerde daha hızlı geliştirme.

Seçim; ekip yapısı, trafik hacmi, devops olgunluğu ve versiyonlama stratejisine göre değişir.

Tasarım ilkeleri ve iyi uygulamalar

• Tek sorumluluk: Kompozit endpoint yalnızca bir ekranın veya işlem adımının ihtiyaç duyduğu verileri birleştirsin.
• Sözleşme (contract) yalınlığı: Tek, anlamlı bir DTO kullanın (UserAddDataDto gibi). Aşırı ve gereksiz alanları döndürmeyin.
• Hata ve kısmi cevaplar: Bir kaynağın başarısızlığı tüm yanıtı düşürmesin; gerekiyorsa boş dizi ve uyarı metadata’sı ile dönün.
• Önbellekleme: Roller/departmanlar gibi sık değişmeyen veriler için uygun süreli cache (HTTP cache headers, gateway cache, dağıtık cache) uygulayın.
• Zaman aşımı & retry: Her alt çağrı için makul timeout ve retry politikaları belirleyin; patikaları izlemek için tracing ekleyin.
• Versiyonlama: Kompozit uç noktaların /v1, /v2 gibi sürümleri olsun; UI değiştikçe geriye dönük uyumu koruyun.
• Güvenlik: Kimlik/rol doğrulamasını kompozit katmanda tekrar değerlendirin; yalnızca yetkili alanları döndürün.

Ne zaman kaçınmalı?

• Bağımsızlık gerekiyorsa: Bir ekran, farklı modüller tarafından farklı zamanlarda ihtiyaç duyulan heterojen verileri istiyor ve bunlar birlikte anlam ifade etmiyorsa, kompozit yerine ayrı çağrılar daha doğru olabilir.
• Aşırı şişkin sözleşmeler: “Hepsini döndür” yaklaşımı payload’ı büyütür, sürüm yönetimini zorlaştırır.
• Yoğun gerçek zamanlılık: Çok hızlı güncellenen verilerde tek büyük kompozit istek yerine, hedefe yönelik küçük ve sık istekler daha etkili olabilir.

Performans & gözlemlenebilirlik

Kompozit katman, L7’de kritik bir durak olduğu için ölçülebilir olmalıdır:

• Tracing: Her alt servise giden çağrıları trace id ile ilişkilendirin.
• Metri̇kler: P95/P99 yanıt süreleri, hata oranları, cache hit oranı.
• Log korelasyonu: İstek başına ilişkili logları tek yerde inceleyebilme.

Sonuç: Küçük bir birleşim, büyük bir fark

Kompozit API’ler; UI’nin ihtiyaç duyduğu verileri tek istekte birleştirerek hem kullanıcı deneyimini iyileştirir hem de istemci kodunu sadeleştirir. “Kullanıcı ekleme” örneğinde roller ve departmanları tek uç noktada birleştirmek; ilk yüklenme süresini kısaltır, hata yönetimini merkezileştirir ve bakım maliyetini düşürür.

Prensip basit: Bir ekran = bir kompozit sözleşme. Doğru konumlandırma, sağlam sözleşme tasarımı ve ölçülebilirlik ile kompozit katman, mikroservis mimarinizin görünmez hızlandırıcısı olur.