API Ağ Geçidi ve Yönlendirme

1) Mimaride API Ağ Geçidi Rolü

• Gelen trafiği kabul eder (HTTP/HTTP2/HTTP3, WebSocket, gRPC)
• Kurallara göre rotalar (host/path/headers/method/query/geo/weight/health);
• Uçtan uca politikalar uygular: kimlik doğrulama/yetkilendirme, hız sınırlama, WAF, CORS, önbelleğe alma;
• Dönüşümler gerçekleştirir (başlıkların/gövdelerin normalleştirilmesi, gRPC↔JSON, GraphQL dikişi);
• Stabilite sağlar (zaman aşımları, yeniden denemeler, devre kesici, aykırı algılama);
• gözlemlenebilirlik ve faturalandırma sağlar (günlükler, metrikler, izler, kotalar);
• İç topolojiyi izole eder (servis ağı, özel hizmetler).

Genellikle çiftler halinde kullanılır: Edge/API-Gateway + Ingress/Mesh (Envoy/Istio/Linkerd) - birincisi dış politikaya karar verir, ikincisi - doğu-batı.

2) Tipik topolojiler

Tek küresel ağ geçidi (CDN/edge POP - L7 ağ geçidi - hizmetler) - basit, merkezi politikalar.
Bölgesel ağ geçitleri (bölge başına) + akıllı coğrafi/gecikme yönlendirmesi.
Çok kiracılı: özel rotalar/alt alanlar/anahtarlar, kotalar ve kiracı başına sınırlar.
Hibrit: On-prem + bulut, özel bağlantı/peering, API ağ geçidinin arkasındaki özel arka uçlar.

3) L7 Yönlendirme Kuralları

• Host/Path: 'api. örnek. com '-'/v1/orders/'.
• Başlıklar: 'X-Client', 'X-Region', 'User-Agent', 'Accept'.
• Yöntem/İçerik Tipi: JSON/Proto/GraphQL'yi ayırt etme.
• Sorgu/Fragment: dikkatli - önbellek/varyantları etkiler.
• Geo/Latency: En yakın POP/bölge, bozulma altında yük devretme.
• Ağırlıklı/Kanarya: Trafik dağılımı 90/10, 50/50, çerez ile yapışkan.
• Oturum yakınlığı: Anahtar/belirteç tabanlı karma (ölçeklendirirken dikkatli olun).

yaml nginx. ingress. kubernetes. io/canary: "true"
nginx. ingress. kubernetes. io/canary-weight: "10" # 10% traffic to new backend

yaml match: { prefix: "/orders", headers: [{name: "X-Experiment", exact_match: "new"}] }
route: { cluster: orders-v2 }

4) Protokoller ve uyumluluk

REST/JSON - varsayılan, istemci doğrulama/oluşturma için OpenAPI'yi açıklayın.
gRPC - HTTP/2 üzerinden ikili Proto; Harici istemciler için, gRPC-JSON kod dönüştürme kullanın.
GraphQL - hizmetleri toplar; Çevre üzerinde, sorguların karmaşıklığını/derinliğini izleyin.
WebSocket/SSE - çift yönlü/push; Yapışkan ve zaman aşımlarını düşünün.
HTTP/2/3 (QUIC) - çoğullama/hızlı başlangıç; WAF/proxy uyumluluğunu doğrulayın.

5) Güvenlik: kimlik doğrulama ve yetkilendirme

5. 1 Ulaşım

TLS 1. 2 + çevre, HSTS, OCSP zımbalama, PFS.
B2B/internal API ve makineden makineye için mTLS.
IP allowlist/denylist, coğrafi kısıtlamalar.

5. 2 Uygulama katmanı

OAuth2/OIDC: JWT taşıyıcı belirteçleri, imza/son kullanma tarihi/kitle doğrulaması.
NMAS/signatures: date + canonized line + signature (AWS-like) - yerine koyma, tekrarlamaya karşı koruma (nonce/time window).
API anahtarları: yalnızca tanımlayıcı olarak; Haklar - RBAC/ABAC/kapsamları aracılığıyla.
CORS: açık izin kaynağı, uçuş öncesi önbellek.
WAF: imzalar (OWASP API Top 10), anomali, bot koruması, özyinelemeli JSON alanları.
DDoS/Kötüye Kullanım: bağlantı sınırlaması, token-bucket/Leaky bucket, birst + ortalama hız, dinamik yasaklar.

yaml plugins:
- name: oidc config: { issuer: "...", client_id: "...", client_secret: "...", scopes: ["orders. read"] }
- name: rate-limiting config: { minute: 600, policy: local }

6) Doğrulama, dönüşüm ve uyumluluk

Şemalar: OpenAPI/JSON-Schema/Protobuf'a göre gövde/başlıklar/parametrelerin doğrulanması.
Dönüşümler: alan normalleştirme, PII maskeleme, korelasyon başlıklarının eklenmesi ('traceparent', 'x-request-id').
Sürüm oluşturma: 'Başlık: X-API-Sürüm', önekler'/v1 ', kaynak sürüm oluşturma; Değer düşüklüğü politikası и Sunset.
Backward-compat: yalnızca add-field; Yeni bir sürüm olmadan değişiklikleri "kırmaktan" kaçının.
Idempotency: POST для 'Idempotency-Key'; Gateway anahtarları TTL ile Redis'te saklar.

7) Esneklik: Bağlantı politikaları

Zaman aşımları: bağlan/oku/yaz; Makul varsayılanlar (örn. 1s/5s/5s).
Yeniden çalışır: sadece güvenli ve idempotent için; Jitter, üstel geri dönüş, maksimum deneme.
Devre kesici: hatalar/gecikme açık; Örnekler için yarı açık.
Aykırı algılama - kötü örnekleri havuzdan kaldırın.
Bulkhead/competition: eşzamanlı rota başına isteklerin sınırları.
Yük devretme: aktif/pasif, bölgesel bozulma.
Gölge trafiği: V2 "gri", karşılaştırma için V1'e paralel olarak çalışır (yanıt üzerinde etkisi yoktur).

yaml circuit_breakers:
thresholds:
- priority: DEFAULT max_connections: 1024 max_pending_requests: 2048 max_retries: 3

8) Önbelleğe alma ve performans

HTTP- кеш: 'Cache-Control', 'ETag/If-None-Match', 'Vary', 'stale-while-revalidate'.
Kenar önbellekleri/POP: Statik ve önbelleğe alınmış API'ler (idempotent GET'ler) için CDN'ler.
Sıkıştırma: 'gzip/br' (zaten sıkıştırılmış sıkıştırmayın).
Request collapsling ("coalescing"): Aynı paralel isteklerin birleştirilmesi.
Yanıt şekillendirme: alanlar/filtreler, imleç tabanlı, boyut sınırları.

9) Gözlemlenebilirlik ve çalışma

Метрики: 'l7 _ req _ total {route, method, code}', 'latency _ ms {p50, p95, p99}', 'upstream _ errors', 'retry _ count', 'cb _ state', '429 _ rate', 'cota _ usage {tenant}'.
Günlükler: yapısal, 'trace _ id/span _ id', 'user _ id/tenant _ id', 'client _ ip'ile.
İzler: W3C Trace Context ('traceparent', 'tracestate'), yukarı akışa yayılır.
Denetim: kim neye neden oldu, hangi haklarla; Hassas API'ler için değişmez depolar.
SLO/SLA: hedef p99, hata bütçesi; Kök seviyesi küresel olandan daha iyidir.

10) Kapasite planı yönetimi

Kiracı/anahtar/müşteri havuzu başına kota, min/saat/gün olarak.
Burst + sürekli limitler; Yumuşatma için sızdıran kova.
Adalet: aşırı yüklendiğinde -'ilk karşılaşılan "yerine adil kuyruk.
Öncelikler: Öncelikli ve özel havuzlara sahip sistem/kritik rotalar.

11) Değişim Yönetimi ve Bültenleri

Kanarya/Mavi-Yeşil: ağırlık yönlendirme; SLO'da otomatik ilerleme (hatalar/gecikme).
Özellik kapıları/arka uç bayrakları: başlık/belirteç ile etkinleştir.
Gölgeleme/diff doğrulayıcıları: cisimlerin/durumların karşılaştırılması, delta toleransları.
Evreleme: tahsis edilmiş alanlar/yollar ('evreleme. api... '), bireysel anahtarlar ve kotalar.

12) Yapılandırma örnekleri

12. 1 NGINX - Temel Limit ve Önbellek Ağ Geçidi

nginx map $http_x_request_id $reqid { default $request_id; }

limit_req_zone $binary_remote_addr zone=perip:10m rate=10r/s;

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

security add_header Strict-Transport-Security "max-age = 31536000" always;

location /v1/ {
limit_req zone=perip burst=30 nodelay;
proxy_set_header X-Request-ID $reqid;
proxy_set_header Authorization $http_authorization;
proxy_connect_timeout 1s;
proxy_read_timeout 5s;

proxy_cache api_cache;
proxy_cache_valid 200 10s;
proxy_cache_use_stale error timeout updating;
proxy_pass http://orders-v1;
}
}

12. 2 Elçi - Denge ve Retray Yönlendirme

yaml routes:
- match: { prefix: "/orders" }
route:
weighted_clusters:
clusters:
- name: orders-v1 weight: 90
- name: orders-v2 weight: 10 retry_policy:
retry_on: "5xx,reset,connect-failure"
num_retries: 2 per_try_timeout: 2s

12. 3 Traefik - ara katman ve başlıklar

yaml http:
middlewares:
secHeaders:
headers:
stsSeconds: 31536000 contentTypeNosniff: true routers:
api:
rule: "Host(`api. example. com`) && PathPrefix(`/v1`)"
service: svc-orders middlewares: ["secHeaders"]

13) Anti-desenler

Hepsi için küresel bir sınır -'iyi komşular "" gürültülü "yüzünden acı çekiyor.
Idempotency olmadan Retrays - yinelenen efektler (ödemeler, varlık oluşturma).
'Timeout'/' max body size' yok saymak işçileri asar/tüketir.
Ağ geçidinde kenar politikalarını ve iş mantığını karıştırma (çevreye ağırlık verme).
Şemaların geçerlilik eksikliği - istemcilerin kırılganlığı ve "kırılma" sürümleri.
Çıplak WebSocket auth/limits/idle-time hariç.
Rotasyonsuz başlıklardaki sırlar; Dahili B2Bs mTLS yok.

14) Test oyun kitapları (Oyun Günleri)

İstek fırtınası: kontrol sınırlayıcı/kota, 429-davranış, bozulma.
Bir kümenin kaybı: yük devretme/ağırlık yeniden dağıtımı; SLO kanaryaları.
Ağırlıklı cevaplar: Maksimum gövde/zaman aşımları; mafsalları kesmek.
Enjeksiyonlar/anomaliler: WAF kuralları, özyinelemeli JSON inhibisyonu, büyük GraphQL derinlikleri.
Trace 'traceparent' yayılımını ve örneklemesini kontrol edemedi.
Sırlar: anahtar rotasyonu/JWKS, belirteç sona ermesi, saat eğriltme toleransı.

15) Uygulama kontrol listesi

• Domains/paths/versions tanımlı, OpenAPI/Proto yayınlanmış.
• TLS/mTLS, HSTS, gizli yönetim ve rotasyon yapılandırılmıştır.
• Kimlik doğrulama (OIDC/HMAC), RBAC/kapsamlar, CORS etkin.
• Kiracı başına sınırlar/kotalar, adil kuyruklar, 429-UX.
• Ağırlık/başlık yönlendirme, kanarya planı ve geri alma.
• zaman aşımı/yeniden deneme/devre kesici/aykırı politikalar.
• Şema doğrulama, dönüşümler, PII maskeleme.
• Edge- кеш/ETag, birleştirme, gzip/br.
• Gözlemlenebilirlik: metrikler, günlükler, izler, gösterge panoları ve uyarılar.
• Runbooks: olaylar, anahtar rotasyonu, blok listeleri, Kara Cuma.

16) SSS

S: API ağ geçidi hizmet ağından nasıl farklıdır?
C: Ağ Geçidi - kuzey-güney (dış çevre, uçtan uca politikalar). Mesh - doğu-batı (intrakluster bağlantı/MTLS/retrai). Genellikle birlikte kullanılır.

S: Auth nerede uygulanır: ağ geçidinde veya hizmetlerde?
C: Her iki seviye: ağ geçidi - kaba taneli (kimlik doğrulama, temel haklar/kotalar), hizmet - ince taneli (etki alanı rolleri/nitelikleri).

S: gRPC-JSON kod dönüştürme ne zaman gereklidir?
C: Dahili gRPC ve dışarısı REST/JSON ve basit istemciler/tarayıcılar gerektirdiğinde.

S: Bir sürüm stratejisi nasıl seçilir?
A: Genel API'ler için - yol'/vN '+ yoksunluk başlıkları ve uzun örtüşme. Dahili - yetenek-bayrakları/uyumluluk şeması için.

17) Toplam

API ağ geçidi sadece bir proxy değil, aynı zamanda bir politika ve esneklik merkezidir. Doğru yönlendirme, güvenlik, sınırlar, doğrulama ve gözlemlenebilirlik, sürümlerin öngörülebilirliğini ve hızını verir. Kenar ağ geçidini servis ağıyla birleştirin, kanaryaları ve kotaları, test arızalarını otomatikleştirin - ve çevre bir darboğaz değil, hızlandırıcınız olacaktır.