API Ağ Geçidi Kalıpları ve Modern Uygulamalar için En İyi Uygulamalar

API ağ geçitleri, tüm kurumsal trafiğin ortalama %83'ünü yöneterek istemci uygulamaları için tek giriş noktası görevi görür. İyi tasarlanmış bir API ağ geçidi, istemci-sunucu iletişimini basitleştirir, güvenlik politikalarını uygular ve tüm hizmetlerde gözlemlenebilirlik sağlar. Kötü tasarlanmış bir sistem bir darboğaz ve tek bir başarısızlık noktası haline gelir.

Bu kılavuz, API ağ geçidi mimarisi kalıplarını, teknoloji seçimini ve web uygulamaları, ERP sistemleri ve e-Ticaret platformları için en iyi uygulama uygulamalarını kapsar.

Önemli Çıkarımlar

• API ağ geçitleri, hizmetler genelinde tekrarları ortadan kaldırmak için kesişen konuları (kimlik doğrulama, hız sınırlama, günlük kaydı) merkezileştirir
• Ağ geçidi düzeyinde hız sınırlaması, arka uç hizmetlerini trafik artışlarından ve kötüye kullanımdan korur
• Devre kesici düzenleri, aşağı yönlü hizmetler sağlıksız olduğunda ardışık arızaları önler
• Ağ geçidi aracılığıyla API sürümü oluşturma, API yüzeyinizin geriye dönük olarak uyumlu bir şekilde geliştirilmesine olanak sağlar

---

Çekirdek Ağ Geçidi Modelleri

Desen 1: Yönlendirme İsteği

Ağ geçidi, istekleri URL yoluna, başlıklara veya diğer istek özelliklerine göre uygun arka uç hizmetine yönlendirir.

# Nginx as API gateway
upstream api_service {
    server api-1:3001;
    server api-2:3001;
}

upstream auth_service {
    server auth:9000;
}

upstream web_service {
    server web:3000;
}

server {
    listen 443 ssl;
    server_name api.example.com;

    location /api/v1/ {
        proxy_pass http://api_service;
    }

    location /auth/ {
        proxy_pass http://auth_service;
    }

    location / {
        proxy_pass http://web_service;
    }
}

Model 2: Kimlik Doğrulama ve Yetkilendirme

Her hizmette uygulanmasını önlemek için kimlik doğrulamayı ağ geçidinde merkezileştirin.

// NestJS middleware for JWT validation at the gateway level
@Injectable()
export class GatewayAuthMiddleware implements NestMiddleware {
  constructor(private readonly jwtService: JwtService) {}

  async use(req: Request, res: Response, next: NextFunction) {
    // Skip public endpoints
    if (this.isPublicEndpoint(req.path)) {
      return next();
    }

    const token = this.extractToken(req);
    if (!token) {
      throw new UnauthorizedException('Missing authentication token');
    }

    try {
      const payload = await this.jwtService.verifyAsync(token);
      req['user'] = payload;
      next();
    } catch {
      throw new UnauthorizedException('Invalid token');
    }
  }

  private extractToken(req: Request): string | undefined {
    // Check cookie first, then Authorization header
    return req.cookies?.ecosire_auth
      || req.headers.authorization?.replace('Bearer ', '');
  }

  private isPublicEndpoint(path: string): boolean {
    const publicPaths = ['/health', '/api/v1/products', '/api/v1/blog'];
    return publicPaths.some(p => path.startsWith(p));
  }
}

Model 3: Hız Sınırlaması

// Rate limiting configuration per endpoint type
const rateLimits = {
  public: { windowMs: 60000, max: 100 },     // 100 req/min for public APIs
  authenticated: { windowMs: 60000, max: 500 }, // 500 req/min for authenticated users
  admin: { windowMs: 60000, max: 1000 },       // 1000 req/min for admin
  webhooks: { windowMs: 60000, max: 50 },       // 50 req/min for webhooks
};

Desen 4: Devre Kesici

Aşağı yöndeki bir hizmet başarısız olduğunda devre kesici, ardışık arızaları önler:

[Closed] --> (failures exceed threshold) --> [Open] --> (timeout expires) --> [Half-Open]
    ^                                                                            |
    |                                        (success)                           |
    +--------------------------------------------------------------------<-------+
    |                                        (failure)                           |
    |                                           +-------->  [Open]

Devletler:

• Kapalı: İstekler normal şekilde iletilir. Arıza sayısını takip edin.
• Açık: Tüm istekler, hizmeti çağırmadan hemen başarısız olur. Önbelleğe alınmış/geri dönüş yanıtını döndür.
• Yarı Açık: Bir isteğin geçmesine izin verin. Başarılı olursa devreyi kapatın. Başarısız olursa yeniden açın.

Desen 5: Yanıt Önbelleğe Alma

# Cache GET responses for public endpoints
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api_cache:10m max_size=1g inactive=60m;

location /api/v1/products {
    proxy_pass http://api_service;
    proxy_cache api_cache;
    proxy_cache_valid 200 5m;
    proxy_cache_valid 404 1m;
    proxy_cache_key "$scheme$request_method$host$request_uri";
    add_header X-Cache-Status $upstream_cache_status;
}

---

API Sürüm Oluşturma Stratejileri

Öneri: URL yolu sürümü oluşturma. Ağ geçidi düzeyinde yönlendirmesi en açık, en hata ayıklanabilir ve en kolay olanıdır.

Kesintili ve Kesintisiz Değişiklikler

---

Ağ Geçidi Teknolojisi Karşılaştırması

Çoğu KOBİ için: Nginx yeterlidir. Yönlendirme, SSL sonlandırma, hız sınırlama ve önbelleğe alma işlemlerini milisaniyeden kısa sürede gerçekleştirir. Gelişmiş eklenti özelliklerine (OAuth2, istek dönüştürme, analiz) ihtiyaç duyduğunuzda Kong'a yükseltin.

---

Ağ Geçidinde Gözlemlenebilirlik

Günlük Talep Et

log_format gateway '$remote_addr - $remote_user [$time_local] '
                   '"$request" $status $body_bytes_sent '
                   '"$http_referer" "$http_user_agent" '
                   '$request_time $upstream_response_time '
                   '$http_x_request_id';

access_log /var/log/nginx/gateway.log gateway;

Metrik Koleksiyonu

Bu ölçümleri ağ geçidi düzeyinde izleyin:

• Uç nokta, yöntem ve durum koduna göre İstek oranı
• Uç noktaya göre gecikme dağılımı (P50, P95, P99)
• Uç nokta ve hata türüne göre hata oranı
• Müşteriye göre oran sınırı isabetleri
• Uç noktaya göre Önbellek isabet oranı
• Önümüzdeki yanıt süresi ile toplam yanıt süresi karşılaştırması

---

Ağ Geçidinde Hata İşleme

Tutarlı Hata Yanıtları

Ağ geçidinin farklı arka uç hizmetlerinden gelen hata yanıtlarını normalleştirmesi gerekir:

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The requested service is temporarily unavailable",
    "requestId": "req_abc123",
    "timestamp": "2026-03-16T14:32:01Z"
  }
}

Yeniden Deneme ve Zaman Aşımı Yapılandırması

location /api/ {
    proxy_pass http://api_service;

    # Timeout configuration
    proxy_connect_timeout 5s;
    proxy_send_timeout 30s;
    proxy_read_timeout 30s;

    # Retry on connection errors only (not on 5xx)
    proxy_next_upstream error timeout;
    proxy_next_upstream_tries 2;

    # Custom error pages
    error_page 502 503 504 /api-error.json;
}

Zarif Bozulma

Kritik olmayan bir arka uç hizmeti kapalı olduğunda ağ geçidi, hata döndürmek yerine önbelleğe alınmış yanıtları veya geri dönüş verilerini sunabilir:

---

Ağ Geçidi Güvenlik Modelleri

Doğrulama İste

Arka uç hizmetlerine iletmeden önce istek yapısını doğrulayın:

• Bilinmeyen içerik türlerine sahip istekleri reddet
• Uç nokta başına maksimum istek gövdesi boyutunu zorunlu kılın
• Gerekli başlıkları doğrulayın (API sürümü, içerik türü)
• Şüpheli başlıkları soyun (atlamadan atlamalı başlıklar, sunucu içi başlıklar)

Yönetici Uç Noktaları için IP İzin Verilenler Listesine Ekleme

location /api/admin/ {
    allow 203.0.113.0/24;  # Office IP range
    allow 10.0.0.0/8;      # Internal network
    deny all;

    proxy_pass http://api_service;
}

Dönüşüm İste

Ağ geçidi, iletmeden önce başlıkları ekleyebilir, değiştirebilir veya kaldırabilir:

location /api/ {
    proxy_pass http://api_service;

    # Add security headers
    proxy_set_header X-Request-ID $request_id;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP $remote_addr;

    # Remove internal headers from responses
    proxy_hide_header X-Powered-By;
    proxy_hide_header Server;
}

---

Sıkça Sorulan Sorular

Monolitik bir uygulama için bir API ağ geçidine ihtiyacımız var mı?

Evet ama daha basit olanı. Bir monolit için bile ters proxy olarak Nginx, SSL sonlandırma, hız sınırlama, statik dosya sunumu ve güvenlik başlıkları sağlar. Tek parça için Kong'a veya AWS API Gateway'e ihtiyacınız yoktur ancak internet ile uygulama sunucunuz arasında bir şeye ihtiyacınız vardır.

API ağ geçidi yük devretmesini nasıl hallederiz?

Bir bulut yük dengeleyicinin (AWS ALB, Cloudflare) arkasında birden çok ağ geçidi örneğini çalıştırın. Bir ağ geçidi örneğinin arızalanması durumunda yük dengeleyici, trafiği sağlıklı örneklere yönlendirir. Nginx için aktif durum kontrollerini ve sağlıksız yukarı akışların otomatik olarak kaldırılmasını kullanın.

API ağ geçidi kimlik doğrulamayı mı yönetmeli yoksa her hizmet mi yapmalı?

Ağ geçidi kimlik doğrulamayı gerçekleştirmelidir (belirtecin geçerli olduğunu doğrulamak). Yetkilendirmeyi bireysel hizmetler gerçekleştirmelidir (kimliği doğrulanmış kullanıcının belirli bir eylem için izne sahip olup olmadığının kontrol edilmesi). Bu ayrım, ağ geçidini hafif tutar ve hizmetlerin ayrıntılı erişim kontrolü kararları almasına olanak tanır.

API ağ geçidinde CORS'u nasıl ele alırız?

CORS üstbilgilerinin hizmetler arasında çoğaltılmasını önlemek için CORS'u ağ geçidi düzeyinde yapılandırın. Access-Control-Allow-Origin'ı belirli ön uç etki alanlarınıza ayarlayın (üretimde asla kimlik bilgileriyle * kullanmayın). Arka uç hizmetlerindeki yükü azaltmak için ağ geçidindeki ön kontrol SEÇENEKLERİ isteklerini yönetin.

---

Sırada Ne Var?

API ağ geçidi, altyapınıza açılan ön kapıdır. Görünürlük için izleme ile, koruma için güvenliği güçlendirme ve kapasite planlaması için yük testi ile eşleştirin.

API mimarisi danışmanlığı için ECOSIRE ile iletişime geçin veya altyapı yol haritasının tamamı için DevOps kılavuzumuzu inceleyin.

---

ECOSIRE tarafından yayınlandı - işletmelerin ölçeklenebilir API altyapısı oluşturmasına yardımcı oluyor.