API şlyuz və marşrutlaşdırma

1) Arxitekturada API şlüzünün rolu

• daxil olan trafiki qəbul edir (HTTP/HTTP2/HTTP3, WebSocket, gRPC);
• qaydalara (host/path/headers/method/query/geo/çəki/sağlamlıq);
• keçid siyasətlərini tətbiq edir: autentifikasiya/avtorizasiya, rate limiting, WAF, CORS, caching;
• transformasiyaları yerinə yetirir (başlıqların/cisimlərin normallaşdırılması, gRPC, JSON, GraphQL stitching);
• sabitliyi təmin edir (timeouts, retries, circuit-breaker, outlier detection);
• müşahidə və billing (log, metrika, izləmə, kvota) edir;
• daxili topologiyanı təcrid edir (service mesh, xüsusi xidmətlər).

Tez-tez bir cütdə istifadə olunur: Edge/API-Gateway + Ingress/Mesh (Envoy/Istio/Linkerd) - birincisi xarici siyasəti həll edir, ikincisi - şərq-qərb.

2) Tipik topologiyalar

Vahid qlobal şlüz (CDN/edge POP → L7 gateway → xidmətlər) - sadə, mərkəzləşdirilmiş siyasətçilər.
Regional şlüzlər (per-region) + geo/latentlik üzrə ağıllı marşrutlaşdırma.
Multi-tenant: xüsusi marşrutlar/alt domenlər/açarlar, kvotalar və kirayəçi üçün limitlər.
Hybrid: on-prem + cloud, private link/peering, API şlüzünün arxasında özəl arxa planlar.

3) L7 marşrutlaşdırma qaydaları

• Host/Path: `api. example. com` → `/v1/orders/`.
• Headers: `X-Client`, `X-Region`, `User-Agent`, `Accept`.
• Method/Content-Type: JSON/Proto/GraphQL fərqləndirilməsi.
• Query/Fragment: ehtiyatlı - cache/variantları təsir edir.
• Geo/Latency: ən yaxın ROP/region, deqradasiya zamanı failover.
• Weighted/Canary: 90/10, 50/50 trafik paylanması, sticky cookie.
• Session affinity: açar/token ilə hash-based (ölçmə zamanı diqqətlə).

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) Protokollar və uyğunluq

REST/JSON - defolt, müştərilərin validasiya/generasiya üçün OpenAPI təsvir.
gRPC - HTTP/2 üzərində ikili Proto; xarici müştərilər üçün gRPC-JSON transcoding istifadə edin.
GraphQL - xidmətləri birləşdirir; perimetri complexity/sorğu dərinliyi nəzarət.
WebSocket/SSE - iki yönlü/push; sticky və timeouts nəzərə.
HTTP/2/3 (QUIC) - multiplex/sürətli başlanğıc; WAF/proxy ilə uyğunluğunu yoxlayın.

5) Təhlükəsizlik: autentifikasiya və avtorizasiya

5. 1 Nəqliyyat

TLS 1. 2 + perimetrdə, HSTS, OCSP stapling, PFS.
B2V/daxili API və maşın-maşın üçün mTLS.
IP allowlist/denylist, geo-məhdudiyyətlər.

5. 2 Tətbiq səviyyəsi

OAuth2/OIDC: JWT bearer tokenləri, imzanın/ekspirasiyanın/auditoriyanın yoxlanılması.
NMAS/imzalar: tarix + kanonlaşdırılmış sətir + imza (AWS-oxşar) - saxtakarlıqdan, təkrarlanmadan (nonce/vaxt pəncərəsi) qorunma.
API açarları: yalnız identifikator kimi; hüquqlar - RBAC/ABAC/satınalmalar vasitəsilə.
CORS: açıq allow-origin, pre-flight cache.
WAF: signatures (OWASP API Top 10), anormallik, bot qorunması, rekursiv JSON sahələri.
DDoS/Abuse: connection limiting, token-bucket/Leaky bucket, berst + orta sürət, dinamik qadağan.

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

6) Validasiya, transformasiya və uyğunluq

Sxemlər: OpenAPI/JSON-Schema/Protobuf tərəfindən bədən/başlıq/parametrlərin validasiyası.
Transformasiyalar: sahələrin normallaşdırılması, PII maskalanması, korrelyasiya başlıqlarının əlavə edilməsi ('traceparent', 'x-request-id').
Version: 'Header: X-API-Version', '/v1 'prefiksləri, resurs-version; deprecation policy и Sunset.
Backward-compat: yalnız add-sahə; Yeni versiya olmadan «pozucu» dəyişikliklərdən çəkinin.
Idempotency: `Idempotency-Key` для POST; gateway TTL ilə Redis açarları saxlayır.

7) Sabitlik: birləşmə siyasəti

Timeouts: connect/read/write; ağlabatan defolt (məsələn, 1s/5s/5s).
Retries: yalnız təhlükəsiz və idempotent üçün; Jitter, exponential backoff, maksimum cəhd.
Circuit breaker: səhvlər/gecikmə zamanı açmaq; half-open üçün nümunələr.
Outlier detection: hovuzdan pis halların çıxarılması.
Bulkhead/rəqabət: eyni zamanda per-route sorğu limitləri.
Failover: aktiv/passiv, zonal deqradasiya.
Shadow traffic: müqayisə üçün «boz» V2 paralel V1 (cavab təsiri olmadan).

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

8) Caching və Performance

HTTP-кеш: `Cache-Control`, `ETag/If-None-Match`, `Vary`, `stale-while-revalidate`.
Edge-caches/ROP: Statik və «cashable» API (idempotent GET) üçün CDN.
Compression: 'gzip/br' (artıq sıxılmış sıxılmayın).
Request collapsing («coalescing»): eyni paralel sorğuların birləşməsi.
Response shaping: sahələr/filtrlər, paginasiya (cursor-based), ölçü limitləri.

9) Müşahidə və istismar

Метрики: `l7_req_total{route,method,code}`, `latency_ms{p50,p95,p99}`, `upstream_errors`, `retry_count`, `cb_state`, `429_rate`, `quota_usage{tenant}`.
Qeydlər: struktur, c 'trace _ id/span _ id', 'user _ id/tenant _ id', 'client _ ip'.
Traces: W3C Trace Context ('traceparent', 'tracestate'), axınlara təşviq edin.
Audit: kim nə çağırıb, hansı hüquqlarla; həssas API üçün dəyişməz saxlama.
SLO/SLA: hədəf p99, səhv büdcəsi; rout səviyyəsi qlobal daha yaxşıdır.

10) Bant genişliyi planının idarə edilməsi

Quota per-tenant/açar/müştərilərin hovuzu, min/saat/gün.
Burst + sustained limitləri; hamarlamaq üçün leaky bucket.
Fairness: həddindən artıq yükləndikdə - «ilk görüşən» əvəzinə fair queuing.
Prioritetlər: prioritet və xüsusi hovuzlarla sistemli/kritik marşrutlar.

11) Dəyişikliklər və buraxılışların idarə edilməsi

Canary/Blue-Green: çəki marşrutu; SLO avtomatik təşviqi (səhvlər/gecikmə).
Feature gates/arxa bayraqlar: başlıq/token ilə daxil.
Shadowing/diff validatorları: cisimlərin/statusların müqayisəsi, delta toleransları.
Staging: Xüsusi domenlər/yollar ('staging. api... '), fərdi açarlar və kvotalar.

12) Konfiqurasiya nümunələri

12. 1 NGINX - limit və cache ilə əsas gateway

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 Envoy - tərəzi və retraya görə marşrutlaşdırma

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 - Midlvari və Heders

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-nümunələr

Hamı üçün bir qlobal limit - «yaxşı qonşular» «səs-küylü» səbəbindən əziyyət çəkirlər.
İdempotentlik olmadan retrajlar → effektlərin dublları (ödənişlər, varlıqların yaradılması).
Görməməzlik 'timeout '/' max body size' → donma/worker tükənməsi.
edge siyasətini və biznes məntiqini şlüzdə qarışdırmaq (perimetrin ağırlaşması).
Sxemlərin yoxluğu → müştərilərin kövrəkliyi və «qırıcı» buraxılışlar.
auth/limitlər/idle-time istisna olmaqla çılpaq WebSocket.
Rotasiya olmadan başlıqlarda sirləri; daxili B2B-də mTLS yoxdur.

14) Test Playbook (Game Days)

Fırtına sorğular: yoxlama limiter/quota, 429-davranış, deqradasiya.
Bir klasterin itirilməsi: failover/çəkinin yenidən paylanması; SLO kanarya.
Ağır cavablar: max body/timeouts; birləşmələrin kəsilməsi.
Enjeksiyon/anomaliyalar: WAF qaydaları, rekursiv JSON qadağası, GraphQL böyük dərinliklər.
Tracking uğursuzluğu: 'traceparent' təbliğatının və semplemenin yoxlanılması.
Sirləri: açar rotasiyası/JWKS, tokenlərin müddəti, clock-skew toleransı.

15) Giriş çek siyahısı

• OpenAPI/Proto tərəfindən yayımlanan domenlər/yollar/versiyalar müəyyən edilmişdir.
• Özelleştirilmiş TLS/mTLS, HSTS, gizli idarəetmə və rotasiya.
• Autentification (OIDC/HMAC), RBAC/CORS daxildir.
• Limitlər/kvotalar per-tenant, ədalətli növbələr, 429-UX.
• Tərəzi/başlıq marşrutu, kanarya planı və rollback.
• timeout/retry/circuit-breaker/outlier siyasəti.
• Sxemlərin validasiyası, transformasiya, PII maskalanması.
• Edge-кеш/ETag, coalescing, gzip/br.
• Müşahidə: metriklər, yuvalar, yollar, daşbordlar və alertlər.
• Runbooks: hadisələr, açar rotasiyası, blok siyahıları, «qara cümə».

16) FAQ

Q: API qapısı xidmət çantasından nə ilə fərqlənir?
A: Şlyuz - north-south (xarici perimetri, keçid siyasətləri). Mesh - east-west (interclaster bağlılığı/MTLS/retrai). Çox vaxt birlikdə istifadə olunur.

Q: auth harada həyata keçirilir: şlüz və ya xidmətlər?
A: Hər iki səviyyə: şluz - coarse-grained (autentifikasiya, əsas hüquqlar/kvotalar), xidmət - fine-grained (domen rolları/atributlar).

Q: gRPC-JSON transcoding nə vaxt lazımdır?
A: Nə zaman daxili gRPC və Outlet REST/JSON və sadə müştərilər/brauzerlər tələb olunur.

Q: Version strategiyasını necə seçmək olar?
A: ictimai API üçün - yol '/vN '+ deprivasiya başlıqları və uzun overlap. Daxili üçün - capability bayraqları/uyğunluq sxemi.

17) Nəticələr

API-şlyuz sadəcə «proksik» deyil, siyasət və sabitliyin mərkəzidir. Düzgün marşrutlaşdırma, təhlükəsizlik, limitlər, validasiya və müşahidə, buraxılışların proqnozlaşdırılması və sürətini təmin edir. Edge şlyuzunu xidmət çantası ilə birləşdirin, kanaryaları və kvotaları avtomatlaşdırın, nasazlıqları sınayın və perimetr şüşə boynunuza deyil, sürətləndiricinizə çevriləcəkdir.