API Gateway Mimari Diyagramı: Yönlendirme, Kimlik Doğrulama, Hız Limitleri ve BFF'ler

API gateway, her mimari diyagramda bulunan ama çok azında açıklanan kutudur. Uçta durur ve zamanla sorumluluk toplar: yönlendirme, kimlik doğrulama, hız limitleri, istek dönüştürme ve bazen hiç üstlenmemesi gereken iş kuralları. Diyagram yalnızca bir gateway simgesinden geçen bir ok gösterdiğinde, bunlardan hangisini yaptığını kimse anlayamaz ve sorular bir incelemede değil, bir olay sırasında ortaya çıkar.

Bu yazı yaygın bir kurulum için API gateway mimari diyagramı oluşturuyor: tek bir gateway'in arkasında bir web uygulaması, mobil uygulamalar ve iş ortakları, her frontend için de bir backend. Gateway'in ne yapması ve ne yapmaması gerektiğini, token kontrollerinin ve hız limitlerinin nasıl çalıştığını ve diyagramın gerçek soruları yanıtlaması için nelerin etiketlenmesi gerektiğini anlatıyor.

Gateway'de neler olmalı

Yük dengeleyici istekleri örneklere dağıtır; çağıranın kim olduğunu bilmez. Service mesh, sistemin içindeki servisler arası trafiği yönetir. Gateway ise dışarıdan gelen trafiği yönetir ve istemcileri tanır: token'larını, rotalarını ve kotalarını. Birçok sistem üçünü birden çalıştırır.

Uçta token kontrolü

Örnekte istemciler kimlik sağlayıcıyla oturum açar ve her istekle bir JSON Web Token (RFC 7519) gönderir. Gateway imzayı, sağlayıcıdan JWKS belgesi olarak alıp önbelleğe koyduğu açık anahtarlarla doğrular ve claim'leri kontrol eder: yayımlayan (iss), hedef kitle (aud) ve son kullanma zamanı (exp).

RFC 8725 içindeki güncel JWT en iyi uygulamalarına burada uymaya değer. Bir kütüphane izin verilen algoritmaları belirtmenize olanak tanımalı ve başkalarını kullanmamalıdır; bu yüzden token başlığına güvenmek yerine listeyi yapılandırın. Tek bir yayımlayıcı birden çok uygulama için token ürettiğinde, token bir hedef kitle taşımalı ve her uygulama hedef kitlenin kendisi olup olmadığını kontrol etmelidir.

Geçerli bir token, çağıranın kim olduğunu söyler. Ne yapabileceğini söylemez. Gateway eksik bir scope'u reddedebilir, ama bu kullanıcının bu siparişi değiştirip değiştiremeyeceğine yine servis karar verir.

Hız limitleri

IP adresine göre değil, istemciye göre sayın. NAT arkasında birçok kullanıcı tek bir adresi paylaşabilir, tek bir kazıyıcı da birçok adres kullanabilir. Limiti API anahtarına, OAuth istemcisine ya da kullanıcıya bağlayın.

Sayaçları paylaşın. Her biri kendi başına sayan birkaç gateway örneğiyle dakikada 100'lük bir limit, örnek başına 100 olur. Redis gibi paylaşılan bir depo, tüm örnekler genelinde istemci başına tek bir sayı tutar.

Bir algoritma seçin ve yazın. Sabit pencere her dakika sıfırlanır ve sınırda ani yüklenmelere izin verir. Kayan pencere bunu yumuşatır. Token kovası, ortalama bir hızı korurken belirli bir boyuta kadar kısa ani yüklenmelere izin verir.

429 ile yanıt verin. RFC 6585, 429 Too Many Requests kodunu tanımlar. Yanıt durumu açıklamalıdır ve Retry-After içerebilir; RFC 9110 bu alanı bir HTTP tarihi ya da beklenecek saniye sayısı olarak tanımlar. RFC 6585, sunucunun istemciyi nasıl tanıdığını ya da istekleri nasıl saydığını söylemez: o kısım sizin tasarımınızdır, bu yüzden diyagrama koyun. Bir IETF taslağı standart RateLimit ve RateLimit-Policy başlık alanlarını tanımlıyor, ancak bu yazının yazıldığı Ekim 2026 itibarıyla hâlâ taslak.

Sayaç deposu çöktüğünde ne olacağına karar verin. Açık başarısız olmak (fail open) API'yi limitsiz de olsa ayakta tutar; kapalı başarısız olmak (fail closed) servisleri korur ve trafiği reddeder. Bilinçli bir karar olduğu ve kazara olmadığı sürece ikisi de doğru olabilir.

Frontend'e özel backend'ler (BFF)

Sam Newman'ın Backends For Frontends deseni, tek bir genel amaçlı API backend'i yerine her kullanıcı deneyimi için sunucu tarafında bir bileşen koyar. Her BFF tek bir arayüze sıkıca odaklanır ve genellikle o arayüzü geliştiren ekip tarafından sürdürülür; böylece ekip ekranları değiştikçe API'yi de değiştirebilir. Ortak, genel amaçlı bir backend darboğaza dönüşme eğilimindedir ve yazı, birleştirme yapan uç servislerin zamanla şişkin kod biriktirdiğini belirtir.

Kaç BFF olmalı? Newman, basit bir kuralı Stewart Gleadow'a atfeder: bir deneyim, bir BFF. İki uygulama aynı deneyimi sunuyorsa ve ikisinin sahibi aynı ekipse tek bir BFF'yi paylaşabilirler; örneğin SoundCloud, iOS ve Android dinleyici uygulamaları için tek bir BFF kullanır.

İş ortakları farklıdır. Bir ekrana göre biçimlenmiş bir API değil, kararlı ve sürümlü bir API'ye ihtiyaçları vardır; bu yüzden rotaları BFF olmadan servislerin genel API'sine gider.

Örnek: bir çevrimiçi mağaza

Mağazanın bir React web uygulaması, iOS ve Android uygulamaları ve bir API üzerinden sipariş oluşturan iş ortakları var. Bir WAF trafiği gateway'den önce filtreler. Gateway token'ları doğrular, istemci başına istekleri Redis'te sayar ve yol önekine göre yönlendirir. Web ve mobil ekiplerinin her birinin bir BFF'si var ve iki BFF de özel ağdaki Orders, Catalog ve Accounts servislerini çağırır. İş ortağı çağrıları doğrudan Orders servisinin sürümlü API'sine gider.

Nasıl okunur:

• Soldan sağa, tek bir istek. Bir istemci WAF üzerinden gateway'i çağırır; gateway isteği bir BFF'ye ya da iş ortağı API'sine yönlendirir.
• Kesikli kenarlar istek yolunun dışındadır. Web uygulaması kimlik sağlayıcıyla oturum açar, gateway de sağlayıcının imzalama anahtarlarını alıp önbelleğe koyar.
• Gateway'in altında, Redis tüm gateway örneklerinin paylaştığı hız limiti sayaçlarını tutar.
• Özel ağın içinde, her BFF yalnızca ekranlarının ihtiyaç duyduğu servisleri çağırır.
• Markdown bloğu gateway politikasıdır: neyi kontrol ettiği, limit ve servislere bıraktıkları.

Neler etiketlenmeli

• Rotalar, her backend için yol önekleri ya da host'lar olarak.
• Her girişte kimlik doğrulama: token türü, kimin yayımladığı ve gateway'in neyi kontrol ettiği.
• Limitler: anahtar, sayı ve pencere, istemcinin geri ne aldığı.
• Gateway'deki zaman aşımları ve yeniden denemeler. Uçtaki yeniden denemeler zorlanan bir servisin yükünü katlar.
• Hata davranışı: kimlik sağlayıcı, sayaç deposu ya da bir backend kullanılamadığında ne olduğu.
• Sahiplik. Gateway yapılandırmasının sahibi çoğu zaman platform ekibidir; BFF'lerin sahibi ise arayüz ekipleri.

Sık yapılan hatalar

• Gateway'de iş mantığı. Dönüştürmeler ve koşullar, kimsenin test edemediği kurallara dönüşür. Gateway'i ince tutun.
• Tek güvenlik kontrolü olarak gateway. Arkasındaki servisler bir isteğe yalnızca oraya ulaştı diye güvenmemelidir. Sıfır güven mimarisi diyagramı, her adımda kontrollerin nasıl çizileceğini gösterir.
• Yalnızca IP başına limitler; bunlar ortak adresleri paylaşan kullanıcıları cezalandırır ve adres değiştiren istemcileri kaçırır.
• Her örnekte yerel sayaçlar; bunlar limiti örnek sayısıyla çarpar.
• Her şey için tek bir BFF; bu yine genel amaçlı bir backend demektir.
• Ayrıntısız bir 429. Ne kadar bekleyeceğini bilmeyen istemciler tahmin eder ve genellikle çok kısa tahmin eder.

Gateway'in arkasında olanlar için mikroservis mimarisi diyagramına bakın. Kubernetes'te Kubernetes Ingress diyagramı, çoğu zaman gateway'in önünde duran ya da onun bazı parçalarının yerini alan katmanı anlatır.

Archboard'da oluşturun

1. Google ya da GitHub ile giriş yapın ve bir diyagram oluşturun.
2. C4 Modeli paketinden web uygulaması ve mobil uygulama için birer Konteyner, iş ortağı için bir Harici sistem ekleyin.
3. Güvenlik paketinden bir WAF ve bir Kimlik sağlayıcı ekleyin.
4. Bulut paketinden bir API ağ geçidi, Veri paketinden de hız limiti sayaçları için bir Redis düğümü ekleyin.
5. Temel paketinden Private network adlı bir Çerçeve ekleyin; içine iki BFF ve üç servis için C4 Modeli paketinden Konteyner düğümleri koyun.
6. Bunları soldan sağa bağlayın, her rotayı yoluyla etiketleyin ve oturum açma ile anahtar alma kenarlarını kesikli yapın. Gateway politikasını içeren bir Markdown bloğunu Temel paketinden ekleyin.

Örnek 14 diyagram düğümü kullanıyor ve Free planın sınırları içinde kalıyor.

SSS

API gateway ile yük dengeleyici aynı şey mi? Hayır. Yük dengeleyici istekleri örneklere dağıtır. Gateway ise API isteklerini anlar: rotaları, token'ları ve kotaları. Birçok gateway bir yük dengeleyicinin arkasında çalışır.

API gateway'im varsa service mesh'e ihtiyacım var mı? İkisi farklı sorunları çözer. Gateway dışarıdan gelen trafiği yönetir; mesh ise karşılıklı TLS ve yeniden denemeler gibi servisler arası çağrıları yönetir. İkisini birden çalıştırıyorsanız ayrı çizin.

Gateway zaten doğruladıysa servisler token'ı yine doğrulamalı mı? Evet, güvendikleri claim'ler için. Gateway kötü token'ları erkenden reddeder; her servis ise eylemi yine kendisi yetkilendirir.

Kaç BFF'im olmalı? Kullanıcı deneyimi başına bir tane. Aynı deneyimi sunan ve sahibi aynı ekip olan iki uygulama tek bir BFF'yi paylaşabilir.

Bir 429 yanıtı neler içermeli? Kısa bir açıklama ve beklenecek saniye sayısını içeren bir Retry-After başlığı; böylece istemciler hemen yeniden denemek yerine geri çekilir.

Ücretsiz başlayın — tek kullanıcı, kredi kartı gerekmez.