API Gateway și rutare

1) API Gateway Rol în arhitectură

• Acceptă traficul de intrare (HTTP/HTTP2/HTTP3, WebSocket, gRPC)
• trasee conform regulilor (gazdă/cale/antet/metodă/interogare/geo/greutate/sănătate);
• aplică politici end-to-end: autentificare/autorizare, limitarea ratei, WAF, CORS, caching;
• efectuează transformări (normalizarea anteturilor/corpurilor, gRPC↔JSON, cusăturile GraphQL);
• oferă stabilitate (timeout, retries, circuit-breaker, detectare outlier);
• dă observabilitate și facturare (busteni, metrici, urme, contingente);
• izolează topologia internă (mesh de serviciu, servicii private).

Adesea folosit în perechi: Edge/API-Gateway + Ingress/Mesh (Envoy/Istio/Linkerd) - primul decide politica externă, al doilea - est-vest.

2) Topologii tipice

Single global gateway (CDN/edge POP → L7 gateway → services) - politici simple, centralizate.
Gateway-uri regionale (pe regiune) + rutare inteligentă geo/latență.
Multi-chiriaș: rute/subdomenii/chei dedicate, cote și limite pentru fiecare chiriaș.
Hibrid: on-prem + cloud, legătură privată/peering, backend privat în spatele gateway-ului API.

3) Regulile de rutare L7

• Gazdă/Cale: 'api. exemplu. com "→ "/v1/orders/".
• Anteturi: 'X-Client', 'X-Region', 'User-Agent', 'Accept'.
• Metodă/Tip de conținut: distincție JSON/Proto/GraphQL.
• Interogare/Fragment: atent - afectează memoria cache/variante.
• Geo/Latency: cel mai apropiat POP/regiune, failover sub degradare.
• Ponderat/Canar: distribuția traficului 90/10, 50/50, lipicios prin cookie.
• Afinitate sesiune: hash-bazat pe cheie/token (atent atunci când scalare).

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) Protocoale și compatibilitate

REST/JSON - implicit, descrieți OpenAPI pentru validarea/generarea clientului.
gRPC - Proto binar peste HTTP/2; pentru clienții externi, utilizați transcodarea gRPC-JSON.
GraphQL - agregate servicii; pe perimetru, monitorizați complexitatea/adâncimea interogărilor.
WebSocket/SSE - bidirecțional/push; ia în considerare lipicios și timeout.
HTTP/2/3 (QUIC) - multiplexare/pornire rapidă; Verificați compatibilitatea WAF/proxy.

5) Securitate: autentificare și autorizare

5. 1 Transport

TLS 1. 2 + pe perimetru, HSTS, OCSP capsare, PFS.
mTLS pentru B2B/internal API și mașină-la-mașină.
IP allowlist/denylist, geo-constrângeri.

5. 2 Strat de aplicare

OAuth2/OIDC: jetoane purtător JWT, semnătură/expirare/verificare audiență.
NMAS/semnaturi: data + linie canonizata + semnatura (AWS-like) - protectie impotriva inlocuirii, repetarii (fereastra nonce/time).
chei API: numai ca identificator; drepturi - prin RBAC/ABAC/scopes.
CORS: permiteți explicit originea, memoria cache înainte de zbor.
WAF: semnături (OWASP API Top 10), anomalie, protecție bot, câmpuri JSON recursive.
DDoS/Abuz: limitarea conexiunii, token-bucket/găleată Leaky, birst + viteză medie, interdicții dinamice.

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

6) Validare, transformare și compatibilitate

Scheme: validarea corpului/anteturilor/parametrilor conform OpenAPI/JSON-Schema/Protobuf.
Transformări: normalizarea câmpului, mascarea PII, adăugarea anteturilor de corelare ('traceparent', 'x-request-id').
Versioning: 'Antet: X-API-Version', prefixe '/v1 ', resource-versioning; politica de depreciere и Sunset.
Înapoi-compat: numai câmp suplimentar; evita „rupere” modificări fără o versiune nouă.
Idempotency: „Idempotency-Key” для POST; gateway stochează chei în Redis cu TTL.

7) Reziliență: Politici de conectare

Timeout: conectare/citire/scriere; valori implicite rezonabile (ex. 1s/5s/5s).
Retries: numai pentru sigur și idempotent; Jitter, backoff exponenţial, încercări maxime.
Întrerupător de circuit: deschis pe erori/latență; jumătate deschis pentru mostre.
Detectarea exteriorului - eliminați cazurile rele din piscină.
Perete etanș/concurență: limite pentru cererile concurente pe traseu.
Failover: degradare activă/pasivă, zonală.
Trafic în umbră: V2 „gri” rulează paralel cu V1 (fără efect asupra răspunsului) pentru comparație.

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

8) Caching și performanță

HTTP- кеш: „Cache-Control”, „ETag/If-None-Match”, „Vary”, „Stale-în timp ce-revalidate”.
Memorie cache/POP: CDN-uri pentru API-uri statice și cache (idempotente).
Compresie: „gzip/br” (nu comprimați deja comprimat).
Colapsul cererii („coalescing”): combinarea cererilor paralele identice.
Modelarea răspunsului: câmpuri/filtre, limite de dimensiune bazate pe cursor.

9) Observabilitate și funcționare

Метрики: 'l7 _ req _ total {route, method, code}', 'latency _ ms {p50, p95, p99}', 'upstream _ errors',' retry _ count', 'cb _ state', '429 _ rate', 'cota _ usage {chiriaș}'.
Jurnale: structurale, cu 'trace _ id/span _ id',' user _ id/tenant _ id', 'client _ ip'.
Urme: W3C Trace Context ('traceparent', 'tracestate'), se propagă în amonte.
Audit: cine ce a cauzat, cu ce drepturi; magazine imuabile pentru API-uri sensibile.
SLO/SLA: țintă p99, buget de eroare; nivelul rădăcinii este mai bun decât cel global.

10) Managementul planului de capacitate

Cota per chiriaș/cheie/piscină client, în min/oră/zi.
Explozie + limite susținute; găleată scurgeri pentru netezire.
Corectitudine: atunci când este supraîncărcat - coadă echitabilă în loc de „prima întâlnire”.
Priorități: sistem/rute critice cu prioritate și bazine dedicate.

11) Managementul schimbărilor și versiuni

Canare/albastru-verde: rutare greutate; avansul automat al SLO (erori/latență).
Feature gates/backend flags: activați prin antet/token.
Validatoare de umbrire/diff: compararea corpurilor/statusurilor, toleranțelor delta.
Stadializare: domenii/căi alocate ('montare. api... "), chei individuale și cote.

12) Exemple de configurare

12. 1 NGINX - Limita de bază și Gateway Cache

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 - Rutare echilibru și Retray

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 - middleware și anteturi

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-modele

O limită globală a tuturor - „vecinii buni” suferă din cauza „zgomotului”.
Retrogradează fără idempotență → efecte duplicate (plăți, entități creatoare).
Ignorarea „timeout ”/„ dimensiunea maximă a corpului” → atârnă/epuizează lucrătorii.
Amestecarea politicilor de margine și logica de afaceri în gateway (ponderarea perimetrului).
Lipsa validării sistemelor → fragilitatea clienților și eliberările „de rupere”.
WebSocket gol, cu excepția auth/limite/inactiv-timp.
Secrete în titluri fără rotație; fără mTLS în B2Bs interne.

14) Cărți de joc de testare (Zilele jocului)

Furtună de cereri: verificați limitator/cotă, 429-comportament, degradare.
Pierderea unui singur grup: redistribuire failover/greutate; Canari SLO.
Răspunsuri ponderate: max body/timeout; tăierea articulațiilor.
Injecții/anomalii: reguli WAF, inhibare recursivă a JSON, adâncimi mari de GraphQL.
Trace nu a reușit să verifice propagarea și eșantionarea „traceparent”.
Secrete: rotație cheie/JWKS, expirarea token-ului, toleranță ceas-înclinare.

15) Lista de verificare a implementării

• Domenii/căi/versiuni definite, OpenAPI/Proto publicat.
• TLS/mTLS, HSTS, managementul secret și rotația sunt configurate.
• Autentificare (OIDC/HMAC), RBAC/scopes, CORS activat.
• Limite/cote per chiriaș, cozi corecte, 429-UX.
• Greutate/antet rutare, plan canar și rollback.
• timeout/retry/circuit-breaker/outlier policies.
• Validarea schemei, transformări, mascarea PII.
• Edge- кеш/ETag, coalescing, gzip/br.
• Observabilitate: valori, busteni, piese, tablouri de bord și alerte.
• Runbooks: incidente, rotație cheie, liste de bloc, Black Friday.

16) ÎNTREBĂRI FRECVENTE

Î: Cum diferă gateway-ul API de plasa de serviciu?
R: Gateway - nord-sud (perimetrul exterior, politici end-to-end). Mesh - est-vest (conectivitate intracluster/MTLS/retrai). Adesea folosite împreună.

Î: În cazul în care pentru a implementa auth: în gateway sau servicii?
R: Ambele niveluri: gateway - grosier-granulat (autentificare, drepturi de bază/cote), serviciu - fin-granulat (roluri/atribute de domeniu).

Î: Când este necesară transcodarea gRPC-JSON?
R: Atunci când gRPC intern și exterior necesită REST/JSON și clienți/browsere simple.

Î: Cum de a alege o strategie de versionare?
R: Pentru API-urile publice - anteturile de privare de cale „/vN ”+ și suprapunerea îndelungată. Pentru schema internă - capability-flags/compatibility.

17) Totaluri

Gateway-ul API nu este doar un proxy, ci un centru de politici și reziliență. Rutarea corectă, securitatea, limitele, validarea și observabilitatea oferă predictibilitate și viteză de lansare. Combinați gateway-ul de margine cu plasa de serviciu, automatizați canarele și cotele, eșecurile de testare - iar perimetrul va deveni acceleratorul dvs., nu un blocaj.