gateway API e routing

1) Ruolo del gateway API nell'architettura

• Installa le richieste (percorso/header/geo/peso/versione).
• Protegge il perimetro (TLS/mTLS, WAF, DDoS, rate limits, authN/Z).
• Controlla il traffico (canary/AB, shadow/mirror, circuito breaker, retrai, timeout).
• Standardizza protocolli, intestazioni, codici.
• Osserva (fogli, metriche, tracciati, corellazioni).
• Trasforma e valuta (JSON/XML, normalizzazione, schema-validation).

Per i clienti si tratta anche di geo-compilation (blocchi per paese/età), smart routing di pagamento e politiche di gioco responsabile ai margini.

2) Opzioni di instradamento

Path-based: `/api/v1/payments/ → payments-svc`.
Host-based: `eu. api. example. com → eu-edge`, `psp. example. com → psp-proxy`.
Header-based: 'X-Client: partner-A' backend di partner; 'Accept: application/grpc'.
Geo-routing: per IP/ASN/Paese (GDPR/divieti locali, latency).
Weighted/Canary: '90%' sulla vecchia, '10%' sulla nuova versione; una rapida rimonta.
Claim-routing: по `JWT. claims. tier/role/region '(ad esempio high-roller-premium-limite).
Failover: attivo/attivo-passivo tra centro dati/nuvole e PSP.

3) Sicurezza perimetro

TLS everywhere: TLS 1. 2 + sull'esterno, mTLS all'interno (shlyuz↔servisy).
OAuth2/JWT: controllo della firma, revisione'exp/nbf/aud/scope ', rotazione JWKS; kesh validation con TTL.
HMAC firma corpi per webhooks/pagamenti.
Chiavi API per i client di sistema Siamo collegati a quote/ruoli.
WAF: regole di base (injection, protocol anatalies), dimensioni del corpo, deny list dei paesi.
Protezione DDoS: connection limiting, cookie SYN, rate-limit su IP/chiave/endpoint.
Zero-Trust: regole di mandato (SPIFFE/SPIRE, identità dei servizi), il principio dei diritti minimi.
Privacy: modifica del PII nei fogli, maschera PAN/BAN, regole di conservazione.

4) Limiti, quote e protezione contro i bursti

Модели: token bucket, leaky bucket, fixed/sliding window.
I limiti sono per-IP, per-key, per-user, per-route.

• Burst + sustained (ad esempio, «50 rps burst», «10 rps sustain»).
• Protezione Retry-Budget e Slow-Loris (timeout di lettura).
• Quota al giorno/mese per i partner.

5) Trasformazioni e validazione

Normalize intestazioni (trace-id, locale, client-id).
Richiest/Response-mapping (campi/codici, nascosto attributi interni).
Schema validation (OpenAPI/JSON Schema) prima del proxy - Errore precoce 4xx.
Compression/« Accept-Encoding », cache (vedere qui sotto).

6) Cache e prestazioni

Edge-cash per riferimenti, metadati pubblici, configure (TTL, ETAG/If-None-Match).
Micro-cache 1-5 s per GET hot (riduzione del carico di picco).
Negative-cache breve (in 404/empty) - attenzione.
Hedging-richiesti e richieste di replica competitive a p95> soglia.

7) Timeout, retrai, sostenibilità

Timeout: connect/read/write separatamente; Punti di riferimento p95 ragionevoli.
Retrai: metodi idempotent (GET/PUT) c backoff + jitter; retry-budget.
Idampotenza POST: «Idempotency-Key» + deduplicazione sul lato servizio/gateway.
Circuito-Breaker: per errori/latency; prova half-open.
Bullkhead/pool-isolamento per upstream.

8) Versioning e compatibilità

• URI: '/v1/... '(semplice ma «rumoroso»).
• Header/Content-Negotiation: `Accept: application/vnd. app. v2+json`.
• Feature-flag/capability server - per la compatibilità delle modifiche minor.

Criteri: SemVer, finestra di supporto (ad esempio, «v1» = 12-18 mes), grafico di depricaggio, risposte compatibili per le estensioni (aggiungere campi - non rompe).

9) Osservabilità e controllo qualità

La correlazione «traceparent »/« x-sollest-id» è obbligatoria; Andiamo di sotto.
OpenTelemetry: metriche RPS/p50/p95/p99/5xx/4xx, saturation, retry/circuito eventi.
Loghi: JSON strutturali; mascheriamo il PII; livelli per codice.
Trailing di base 5-10% + target per errori/lenti.
SLO/alert: percorsi/clienti (farmacia, latency, errore).

10) Gestione del traffico di rilascio

Blue-Green: cambio DNS/LB.
Canary: peso/segmenti (regione, partner, ruolo).
Shadow/Mirror: copia del traffico per la nuova versione senza risposta al cliente.
Kill-switch - Flag per disattivare rapidamente l'upstream/fici problematico.

11) Routing smart dei pagamenti (iGaming)

Le regole di scelta PSP sono geo, valuta, importo, rischio-score, accessibilità, commissione.
Failover PSP: transizione automatica a «5xx/timeout».
Same-method rule - Restituzioni/conclusioni tramite il metodo originale - Verifica sul bordo.
Idemotività dei pagamenti, chiave su «userId+amount+currency+purpose».
Trasparenza ETA - Il gateway aggiunge gli stati e le cause dei guasti (non i codici PSP).

12) Politiche delle regioni crociate e della compilazione

I filtri geo sono elenchi bianchi/neri dei paesi, limiti di età, range IP.
Dati residenti: instradamento in cluster regionali (GDPR/Locali).
Logi e TTL: archiviazione per regione, anonimizzazione automatica.

13) Esempi di configurazione

13. 1 NGINX (routing + limite + header)

nginx http {
map $http_x_request_id $req_id { default $request_id; }
limit_req_zone $binary_remote_addr zone=per_ip:10m rate=20r/s;

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

Security add_header Strict-Transport-Security "max-age = 31536000" always;
add_header X-Content-Type-Options nosniff;

Limit on IP location/api/v1/{
limit_req zone=per_ip burst=40 nodelay;
proxy_set_header X-Request-Id $req_id;
proxy_set_header X-Client-Ip $remote_addr;
proxy_read_timeout 5s;
proxy_connect_timeout 1s;
proxy_pass http://payments_v1;
}

Canary traffic by header location/api/v2/{
if ($http_x_canary = "1") { proxy_pass http://payments_v2; }
proxy_pass http://payments_v1;
}
}
}

13. 2 Envoy (JWT, rate limit, retries, outlier)

yaml static_resources:
listeners:
- name: https address: { socket_address: { address: 0. 0. 0. 0, port_value: 443 } }
filter_chains:
- filters:
- name: envoy. filters. network. http_connection_manager typed_config:
"@type": type. googleapis. com/envoy. extensions. filters. network. http_connection_manager. v3. HttpConnectionManager route_config:
name: local_route virtual_hosts:
- name: payments domains: ["api. example. com"]
routes:
- match: { prefix: "/api/v1/payments" }
route:
cluster: payments_v1 timeout: 5s retry_policy:
retry_on: "connect-failure,refused-stream,5xx,retriable-status-codes"
num_retries: 2 per_try_timeout: 2s http_filters:
- name: envoy. filters. http. jwt_authn typed_config:
"@type": type. googleapis. com/envoy. extensions. filters. http. jwt_authn. v3. JwtAuthentication providers:
main:
issuer: "https://auth. example. com/"
remote_jwks: { http_uri: { uri: "https://auth. example. com/.well-known/jwks. json" } }
forward: true rules:
- match: { prefix: "/api/" }
requires: { provider_name: "main" }
- name: envoy. filters. http. ratelimit
- name: envoy. filters. http. router clusters:
- name: payments_v1 connect_timeout: 0. 5s type: STRICT_DNS lb_policy: ROUND_ROBIN load_assignment: { cluster_name: payments_v1, endpoints: [{ lb_endpoints: [{ endpoint: { address: { socket_address: { address: payments, port_value: 8080 }}}}]}] }
outlier_detection: { consecutive_5xx: 5, interval: 5s, base_ejection_time: 30s }

14) Assegno fogli

Prima del lancio del percorso

• Schema di autenticazione (JWT/JWKS, chiavi, TTL cache).
• Timeout/retrai/idampotenza configurati.
• Limiti: per-IP, per-key, per-route; quote di partner.
• Convalida lo schema di richieste/risposte.
• Loga e traccia con «trace-id», maschera PII.
• SLO/alert e dashboard.
• Geo-regole/compliance/età verificate.

Transazioni e pagamenti

• Smart routing PSP: regole, priorità, feelover.
• Same-method viene controllato sul bordo.
• Stato e codici di errore trasparenti per il client (senza codice PSP grezzo).

Release

• Canary/AB e kill-switch, piano di ripristino.
• Traffico shadow per la nuova versione, confronto metriche.
• Test di carico e p95 obiettivi.

15) Metriche di qualità (minimo)

Availability/SLO lungo le rotte; error rate 5xx/4xx.
Latency p50/p95/p99 (esterno e interno).
Retry/timeout/circuito eventi (livello di rumore).
Cache hit-ratio e risparmio RPS.
Rate-limit hits e richieste rifiutate.
PSP-routing KPIS: successo, TtW, percentuale di feelover, commissione.

16) Anti-pattern

Un limite totale per tutto.
Retrai immediati senza jitter (aumento della tempesta).
Confida in X-Forwarded-For senza la normalizzazione e l'elenco dei proxy affidabili.
Timeout solidi a parte p95 (false attivazioni).
Trasformazioni rigide che rompono la compatibilità.
Loghi PII/PAN/segreti.
Miscelare l'API interna ed esterna con un unico dominio/criterio.

17) Modelli di risposta e errori (microcopy)

429 Too Many Recests: "È stato raggiunto il limite di richiesta. Ripetere tra n secondi o aumentare la quota nell'ufficio del partner

401/403: "Token non valido/scaduto. Riattivare l'accesso

408/504: "Il servizio risponde oltre le attese. La richiesta non è stata accettata"

Idempotency-conflict: «La query con questo Idempotency-Key è già stata elaborata (stato: successo/rifiuto)».

18) Processo di implementazione (per passo)

1. Il modello di percorso è una mappa di domini/percorsi/regioni.
2. Regole di sicurezza: TLS/mTLS, WAF, authN/Z, chiavi/JWKS.
3. Affidabilità: timeout, retrai, idempotency, circuito-breaker.
4. Osservabilità: loghi/metriche/roulotte, corellazione.
5. Kesh/perf: edge/micro-cache, compressione, connect-pool.
6. Routing dei pagamenti, regole, test, monitoraggio.
7. Release: canary/shadow, kill-switch, piano di ripristino.
8. Compilazione/geo: filtri dei paesi, archiviazione dei dati, età.

Scorciatoia finale

Perimetro rigoroso (TLS/mTLS, WAF, limiti) + traffico controllato (retrai, circuito, canary).
La validazione e la trasformazione al limite sono meno difetti all'interno.
Osservabilità con trace-id e maschere PII non è un'opzione, ma uno standard.
Lo smart routing dei pagamenti e il completamento-geo sono critici per i clienti.
Versioning e politiche di deprecazione sono prevedibili per i partner.