gateway API e routing

1) Ruolo del gateway API nell'architettura

• riceve traffico in entrata (HTTP/HTTP2/HTTP3, WebSocket, gRPC);
• Routing secondo le regole (host/path/headers/method/query/geo/peso/salute);
• applica criteri completi: autenticazione/autorizzazione, rate limiting, WAF, CORS, cache
• esegue trasformazioni (normalizzazione intestazione/corpo, gRPC↔JSON, GraphQL stitching)
• garantisce la stabilità (timeouts, retries, circuito-breaker, outlier detection);
• dà osservazione e billing (fogli, metriche, tracciati, quote);
• isola la topologia interna (service mesh, servizi privati).

Spesso usato in una coppia: Edge/API-Gateway + Ingress/Mesh (Avvoy/Istio/Linkerd) - il primo decide la politica estera, il secondo è l'east-west.

2) Topologie tipiche

Un gateway globale (CDN/edge POP L7 gateway servizi) è semplicemente una politica centralizzata.
Gateway regionali (per-region) + routing intelligente per geo/latenza.
Multi-tenant: percorsi/finestre/chiavi dedicati, quote e limiti per affittuario.
Hybrid: on-prem + cloud, private link/peering, backend privato dietro il gateway API.

3) Regole di instradamento L7

• Host/Path: `api. example. com` → `/v1/orders/`.
• Headers: `X-Client`, `X-Region`, `User-Agent`, `Accept`.
• Method/Content-Type: differenza di JSON/Proto/GraphQL.
• Query/Fragment: attenta - influisce sulle varianti.
• Geo/Latency: RR/regione più vicina, failover in caso di degrado.
• Weighted/Canary: distribuzione del traffico 90/10, 50/50, sticky per cookie.
• Sessione affinity: hash-based per chiave/token (in scala).

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) Protocolli e compatibilità

REST/JSON è un default, descrivere le OpenAPI per la convalida/generazione dei clienti.
gRPC - Proto binario sopra HTTP/2; per i client esterni, utilizzare il gRPC-JSON transcoding.
GraphQL - Aggregare i servizi; sul perimetro, controllare complexity/profondità delle richieste.
WebSocket/SSE - bidirezionale/pugno; tenere conto di sticky e timeouts.
HTTP/2/3 (QUIC) - Multiplexing/avvio rapido verificare la compatibilità con il proxy WAF.

5) Sicurezza: autenticazione e autorizzazione

5. 1 Trasporti

TLS 1. 2 + sul perimetro, HSTS, OCSP stapling, PFS.
mTLS per la V2V/API interna e auto-k-auto.
IP allowlist/denylist, vincoli geo.

5. 2 Livello applicativo

OAuth2/OIDC: token bearer JWT, controllo firma/esposizione/pubblico.
Firma NMAS: data + linea canonizzata + firma (AWS-simile) - Protezione da sostituzione, ripetizione (nonce/timeout).
Chiavi API solo come ID diritti - tramite RBAC/ABAC/scorie.
KORS: allow-origin esplicito, pre-flight kash.
Firma WAF (OWASP API Top 10), anormalia, bot-protezione, JSON ricorsivi.
DDoS/Abuse: connection limiting, token-bucket/leaky bucket, burst + velocità media, bani dinamici.

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

6) Validazione, trasformazione e compatibilità

Schemi: convalida corpo/intestazioni/parametri per OpenAPI/JSON-Schema/Protobuf.
Trasformazioni: normalizzazione dei campi, maschera PII, aggiunta di intestazioni correlate ('traceparent', 'x-sollest-id').
Versioning: «Header: X-API-Variante», prefissi «/v1 », versioning delle risorse; deprecation policy и Sunset.
Backward-compat: solo campo add; Evitate le modifiche «distruttive» senza una nuova versione.
Idempotency: `Idempotency-Key` для POST; gateway conserva le chiavi in Redis con TTL.

7) Sostenibilità: criteri di connessione

Timeouts: connect/read/write; default ragionevoli (ad esempio 1s/5s/5s).
Retries: solo per persone sicure e idipotenti jitter, exponential backoff, massimo tentativi.
Circuito breaker: aprire in caso di errori/latitanza; half-open per i campioni.
Outlier detection - Estrarre le istanze sbagliate dal pool.
Bullkhead/concorrenza - Limiti per le richieste simultanee per-route.
Failover: degrado attivo/passivo, zona.
Shadow traffic: test «grigio» V2 parallelo a V1 (senza effetto sulla risposta) per il confronto.

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

8) Cache e prestazioni

HTTP-кеш: `Cache-Control`, `ETag/If-None-Match`, `Vary`, `stale-while-revalidate`.
Edge-Caschi/ROR: CDN per API statiche e «cache» (Idempotent GET).
Compressione: «gzip/br» (non comprimere già compresso).
Richiest collapsing - Unisce richieste parallele identiche.
Response shaping: campi/filtri, paginazione (cursor-based), limiti di quota.

9) Osservabilità e funzionamento

Метрики: `l7_req_total{route,method,code}`, `latency_ms{p50,p95,p99}`, `upstream_errors`, `retry_count`, `cb_state`, `429_rate`, `quota_usage{tenant}`.
Loghi: strutturali, con'trace _ id/span _ id ',' user _ id/tenant _ id ',' client _ ip '.
Tracciati: W3C Trace Text ('traceparent', 'tracestate').
Verifica: chi ha evocato cosa, con quali diritti; Storage invariabile per API sensibili.
SLO/SLA: p99 target, bilancio degli errori; Il livello di root è migliore di quello globale.

10) Gestione del piano di larghezza di banda

Quota per-tenant/chiave/pool di clienti, in minuti/ore/giorno.
Limiti burst + sostained; leaky bucket per l'antialiasing.
Fairness: in caso di sovraccarico, fair queuing invece del primo incontrante.
Priorità: percorsi di sistema/criticità con priorità e pool selezionati.

11) Gestione delle modifiche e rilascio

Canary/Blue-Green: instradamento di peso Promozione automatica SLO (errori/latitanza).
Feature gates/backend - Abilita per titolo/token.
Shadowing/deff validator: confronto tra corpi/stati, tolleranze per delta.
Gli stage sono i domini/percorsi selezionati ('staging. api... '), chiavi separate e quote.

12) Esempi di configurazione

12. 1 NGINX - gateway base con limite e 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 Avvoy - Routing per peso e retrai

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 - Middlevari e 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-pattern

Un limite globale è che i buoni vicini soffrono a causa dei rumori.
I retrai senza idempotenza registrano effetti duplicati (pagamenti, creazione di entità).
Ignora il «timeout »/« max body size» di sparire/esaurire i worker.
Mescolare regole edge e logiche aziendali in un gateway (perimetro di ingrandimento).
La mancanza di convalida dei circuiti, la fragilità dei clienti e le release.
Nudo a parte auth/limiti/idle-time.
Segreti nelle intestazioni senza rotazione; La mancanza di mTLS nel B2B interno.

14) Test playbook (Game Days)

Tempesta di query: controllo limitatore/quota, comportamento 429, degrado.
Perdita di un cluster: failover/ricarica di peso; La SLO dei canari.
Risposte onerose: max body/timeouts; il taglio delle connessioni.
Iniezioni/anomalie: regole WAF, divieto di JSON ricorsive, grandi profondità di GraphQL.
Traccia non riuscita - Verifica della parolà traceparent "e del sempreverde.
Segreti: rotazione chiavi/JWKS, sospensione token, tolleranza clock-skew.

15) Assegno-foglio di implementazione

• Domini/percorsi/versioni definiti, pubblicato in OpenAPI/Proto.
• Configurato con TLS/mTLS, HSTS, segreto-gestione e rotazione.
• Autenticazione abilitata (OIDC/HMAC), RBAC/scorie, CORS.
• Limiti/quote per-tenant, code giuste, 429-UX.
• Routing per bilancia/intestazione, piano canarini e rollback.
• Criteri timeout/retry/circuito-breaker/outlier.
• Convalida gli schemi, la trasformazione, la maschera PII.
• Edge-кеш/ETag, coalescing, gzip/br.
• Osservabilità: metriche, fogli, piste, dashboard e alert.
• Runbooks: incidenti, rotazione delle chiavi, blocchi, Black Friday.

16) FAQ

Q: Cosa differisce un gateway API da un servizio-mesh?
A: gateway - north-south (perimetro esterno, regole passanti). Mesh - east-west (connettività interna/MTLS/retrai). Spesso usati insieme.

Q: Dove implementare auth in gateway o servizi?
A: Entrambi i livelli: gateway - coarse-grained (autenticazione, diritti di base/quote), servizio - fine-grained (ruoli di dominio/attributi).

Quand'è che hai bisogno di un transcoding?
A: Quando il computer interno e l'esterno richiedono REST/JSON e semplici client/browser.

Q: Come scegliere la strategia di versioning?
A: Per API pubbliche - percorso '/' + titoli di deprivazione e overlap lungo. Per interni, capability-flag/schema di compatibilità.

17) Riepilogo

Il gateway API non è solo un proxic, ma un centro di regole e sostenibilità. Il corretto instradamento, la sicurezza, i limiti, la validazione e l'osservabilità forniscono prevedibilità e velocità di rilascio. Combinare l'edge gateway con il servizio-mesh, automatizzare i canarini e le quote, testare i guasti, e il perimetro diventa il vostro acceleratore, non la gola di bottiglia.