API Geçidi Kalıpları: Yönlendirme, Hız Sınırı ve Kimlik

API Geçidi Mikroservisler Mimari Güvenlik

Mikroservis sayısı arttıkça istemcilerin hangi servise nasıl ulaşacağı ayrı bir sorun hâline gelir. API geçidi (API gateway) bu sorunun tek giriş kapısıdır: kimlik doğrulama, yönlendirme, hız sınırı ve istek dönüşümü gibi her serviste tekrar yazılacak işleri tek yerde toplar. Bu yazı en çok kullanılan geçit kalıplarını ve her birinin ne zaman işe yaradığını anlatıyor.

API geçidi ne yapar

Geçit, servislerin iç yapısını istemciden saklayan bir ön yüzdür. İstemci tek tek servislerle değil, geçitle konuşur; geçit isteği doğru servise iletir. Böylece:

Güvenlik tek yerde toplanır: kimlik doğrulama ve temel yetki kontrolü her serviste ayrı ayrı yazılmaz.

Protokol çevrilir: dışarıya REST ya da gRPC-web, içeride gRPC.

Ortak işler tek yerde yapılır: kayıt, metrik, izleme, CORS, istek boyutu sınırı.

İç yapı değişebilir: servisleri bölmek ya da birleştirmek istemciyi etkilemez.

Temel kalıplar

1. Ön yüz için arka uç (Backend for Frontend, BFF)

Her istemci türü için ayrı, ona göre ayarlanmış bir geçit:

Mobil uygulama   → Mobil BFF
Web tarayıcısı   → Web BFF
Üçüncü taraflar  → Genel API

Hepsi            → Çekirdek servisler

Mobil BFF kısa ve sıkıştırılmış cevaplar döner, web BFF farklı önbellek kuralları uygular. Web için BFF’nin bir güvenlik faydası daha vardır: erişim belirteçleri tarayıcıya hiç verilmez, BFF’de saklanır ve tarayıcı yalnız HttpOnly bir oturum çerezi taşır. Böylece bir XSS açığı token çalınmasına dönüşmez.

2. Yönlendirici

En temel kalıp: istek, yol ya da alan adına göre ilgili servise gider.

GET /api/v1/users/123     → kullanıcı servisi
GET /api/v1/orders/456    → sipariş servisi
GET /api/v2/users/123     → kullanıcı servisi, yeni sürüm

Dikkat edilecek nokta, dış URL yapısını iç servis sınırlarına sıkı bağlamamaktır; sürüm öneki geçişlerde iki sürümü birlikte çalıştırmayı kolaylaştırır.

3. Birleştirici (aggregator)

Bir ekran birden fazla servisin verisine ihtiyaç duyduğunda istemciyi dört ayrı çağrı yapmaya zorlamak yerine geçit bunları paralel çağırıp tek cevap döner:

// GET /dashboard: dört servis paralel çağrılır, biri düşerse sayfa yine açılır
const [user, orders, recommendations, notifications] = await Promise.allSettled([
  userService.get(userId),
  orderService.recent(userId),
  productService.recommendations(userId),
  notificationService.unread(userId),
]);

Promise.allSettled ile önemli olmayan bir parçanın hatası tüm ekranı düşürmez. Birleştirme mantığı karmaşıklaşıyorsa bu, servis sınırlarının yanlış çizildiğine işaret olabilir.

4. Hız sınırı

Arka uçları aşırı trafiğe ve kötüye kullanıma karşı korumak için geçitte sınır konur:

Kurallar:
  kullanıcı başına     dakikada belirli sayıda istek
  API anahtarı başına  saatte belirli sayıda istek
  giriş ve parola sıfırlama gibi hassas uçlarda çok daha düşük sınır

Aşılınca:
  429 Too Many Requests
  Retry-After başlığı
  izleme için kayıt

Token kovası (token bucket) ya da kayan pencere algoritması kullanın. Geçit birden fazla kopya çalışıyorsa sayaç ortak bir depoda (Redis gibi) tutulmalıdır; yoksa her kopya sınırı ayrı sayar.

5. Devre kesici

Bir arka uç servisi yanıt vermediğinde, ona istek göndermeye devam etmek hem kaynak israfıdır hem de sorunu büyütür:

Kapalı      : normal çalışma, istekler geçer
Açık        : servis hata veriyor, istekler beklemeden reddedilir
Yarı açık   : bir süre sonra birkaç deneme isteği geçer

Geçişler:
  art arda hatalar          → Açık
  bekleme süresi doldu      → Yarı açık
  yarı açıkta başarılı istek → Kapalı

Devre kesici, bağlantı zaman aşımını beklemekten çok daha hızlı hata verir ve servisin toparlanmasına alan bırakır.

6. Merkezi kimlik doğrulama

Kimlik doğrulama geçitte yapılır, servisler doğrulanmış kimliği güvenilir bir biçimde alır:

1. İstemci oturum çerezi ya da erişim belirteci gönderir
2. Geçit belirtecin imzasını, süresini ve hedef kitlesini doğrular
3. Geçit, istemciden gelen kimlik başlıklarını siler
4. Geçit doğrulanmış kimliği imzalı bir bağlam olarak servislere iletir
5. Servisler bu imzayı doğrular ve kendi yetki kararını verir

Üçüncü adım çoğu zaman unutulur: istemci X-User-Id gibi bir başlığı kendisi gönderebiliyorsa ve geçit onu silmiyorsa, servisler sahte kimliğe güvenir. Yetkilendirme ise servisten tamamen kalkmamalıdır; geçit “bu kişi kim”i, servis “bu kişi bu kaydı görebilir mi”yi cevaplar.

Yaygın yöntemler:

OAuth 2.0 ve OpenID Connect: kullanıcı girişi ve yetki devri için.

JWT: durum tutmayan, ölçeklenebilir belirteçler; kısa ömürlü tutulmalıdır.

mTLS: servisler arası iletişim için.

Yaygın çözümler

Kong: açık kaynak, eklentilerle genişletilebilir.

Envoy ve Envoy Gateway: Kubernetes Gateway API ile yönetilen modern vekil sunucu.

NGINX: hafif ve olgun ters vekil; basit yönlendirmede güçlü.

YARP: .NET ekipleri için kod içinden yapılandırılan ters vekil kütüphanesi.

AWS API Gateway, Azure API Management: bulut sağlayıcılarının yönetilen servisleri.

Traefik: konteyner ortamlarında dinamik yönlendirme.

İyi uygulamalar

İş mantığını geçide koymayın. Geçit altyapı işlerini yapar; karmaşık dönüşümler servis tasarımında bir soruna işaret eder.

İstek kimliği taşıyın. Her isteğe bir iz kimliği verip servislere iletin; dağıtık izleme bundan başlar.

Yüksek erişilebilirlik planlayın. Geçit tek giriş kapısıdır; birden fazla kopya ve birden fazla bölge.

Gecikmesini izleyin. Geçidin eklediği her milisaniye her isteğe eklenir.

Yapılandırmayı sürümleyin. Geçit kuralları kod gibi gözden geçirilip yayınlanmalıdır.

Yönetim arayüzünü kapatın. Geçidin yönetim ucu internete açık olmamalıdır.

Sözleşmeleri yayınlayın. OpenAPI ya da Protocol Buffers tanımları tüketicilerin bulabileceği bir yerde durmalı.

Örnek: fintech platformu

Ödeme işleyen bir platformda geçidin görevleri:

İstekleri OAuth 2.0 ile doğrulamak
Kullanıcı başına işlem sınırı uygulamak
Ödeme, doğrulama ve bildirim servislerine yönlendirmek
Cevapları tek bir işlem onayında birleştirmek
Arka uçlar için devre kesici çalıştırmak
Denetim için her isteği kaydetmek
Web için REST ile iç servisler arasındaki gRPC’yi çevirmek

Geçit olmadan bu işler servislere dağılır; hem bakımı zorlaşır hem de güvenlik kuralları servisten servise farklılaşır.

Sonuç

API geçidi, ortak işleri tek yerde toplayarak mikroservis mimarisini yönetilebilir kılar. Basit yönlendirmeyle başlayın, ihtiyaç oldukça BFF, hız sınırı ve devre kesici ekleyin. Geçit bir boru hattı değil, sistemin güvenliğini ve güvenilirliğini doğrudan etkileyen bir mimari bileşendir.

Geçit tasarımınızı birlikte gözden geçirmek isterseniz bize yazın.

ByteGurus

Yazar

Tüm yazılara dön