API-шлюз і маршрутизація

1) Роль API-шлюзу в архітектурі

• Маршрутизує запити (по шляху/хедерам/гео/вазі/версії).
• Захищає периметр (TLS/mTLS, WAF, DDoS, rate limits, authN/Z).
• Керує трафіком (canary/AB, shadow/mirror, circuit breaker, ретраї, таймаути).
• Стандартизує протоколи (REST/gRPC/WebSocket), заголовки, коди.
• Спостерігає (логи, метрики, трасування, кореляція).
• Трансформує і валідує (JSON/XML, нормалізація, schema-validation).

Для iGaming це ще й гео-комплаєнс (блокування за країнами/віком), платіжний смарт-роутинг і політики відповідальної гри на краю.

2) Варіанти маршрутизації

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'→ партнерський бекенд;'Accept: application/grpc`.
Geo-routing: по IP/ASN/країні (GDPR/локальні заборони, latency).
Weighted/Canary: «90%» на стару, «10%» на нову версію; швидке відкочування.
Claim-routing: по'JWT. claims. tier/role/region'( наприклад, high-roller → premium-ліміти).
Failover: актив-актив/актив-пасив між ЦОД/хмарами і PSP.

3) Безпека периметра

TLS everywhere: TLS 1. 2 + на зовнішці, mTLS всередині (shlyuz↔servisy).
OAuth2/JWT: перевірка підпису, аудит'exp/nbf/aud/scope', JWKS-ротація; кеш валідації з TTL.
HMAC: підпис тіл для webhooks/платежів.
API-ключі: для системних клієнтів; пов'язуємо з квотами/ролями.
WAF: базові правила (injection, protocol anomalies), розмір тіла, deny-лист країн.
DDoS-захист: connection limiting, SYN cookies, rate-limit на IP/ключ/ендпойнт.
Zero-Trust: мандатні політики (SPIFFE/SPIRE, ідентичності сервісів), принцип найменших прав.
Приватність: редагування PII в логах, маскування PAN/IBAN, політика зберігання.

4) Ліміти, квоти і захист від бурстів

Моделі: token bucket, leaky bucket, fixed/sliding window.
Межі: per-IP, per-key, per-user, per-route.

• Burst + sustained (наприклад,'50 rps burst','10 rps sustain').
• Retry-Budget і Slow-Loris захист (таймаути читання).
• Quota по добі/місяцю для партнерів.

5) Трансформації та валідація

Normalize заголовків (trace-id, locale, client-id).
Request/Response-mapping (поля/коди, приховування внутрішніх атрибутів).
Schema validation (OpenAPI/JSON Schema) до проксирування - рання відмова 4xx.
Compression/' Accept-Encoding', caching (див. нижче).

6) Кешування і продуктивність

Edge-кеш для довідників, публічних метаданих, конфігів (TTL,'ETag '/' If-None-Match').
Micro-кеш 1-5 с на гарячі GET (знижує пікове навантаження).
Negative-cache короткий (на 404/empty) - обережно.
Hedging-requests і конкурентні запити до реплік при р95> поріг.

7) Таймаути, ретраї, стійкість

Таймаути: connect/read/write окремо; розумні p95-орієнтири.
Ретраї: idempotent-методи (GET/PUT) c backoff + джиттер; retry-budget.
Ідемпотентність POST: 'Idempotency-Key'+ дедуплікація на стороні сервісу/шлюзу.
Circuit-Breaker: помилки/latency; half-open проби.
Bulkhead/Pool-ізоляція по апстрімах.

8) Версіонування та сумісність

• URI: '/v1/...'( просто, але «шумить» маршрути).
• Header/Content-Negotiation: `Accept: application/vnd. app. v2+json`.
• Feature-прапори/серверні capability - для сумісності minor-змін.

Політика: SemVer, вікно підтримки (наприклад,'v1'= 12-18 міс), графік деприкацій, сумісні відповіді при розширеннях (додавання полів - не ламає).

9) Спостережуваність і контроль якості

Кореляція: 'traceparent '/' x-request-id'обов'язковий; прокидаємо вниз.
OpenTelemetry: метрики RPS/p50/p95/p99/5xx/4xx, saturation, retry/circuit події.
Логи: структурні JSON; маскуємо PII; рівні за кодами.
Семплювання трейсів: базове 5-10% + цільове на помилки/повільні.
SLO/алерти: за маршрутами/клієнтам (аптайм, latency, помилка).

10) Управління трафіком релізів

Blue-Green: перемикання DNS/LB.
Canary: вагова частка/сегменти (регіон, партнер, роль).
Shadow/Mirror: копія трафіку на нову версію без відповіді клієнту.
Kill-switch: прапор для швидкого відключення проблемного апстріму/фічі.

11) Смарт-маршрутизація платежів (iGaming)

Правила вибору PSP: гео, валюта, сума, ризик-скор, доступність, комісія.
Failover PSP: автоматичний перехід при'5xx/timeout'.
Same-method rule: повернення/висновки через вихідний метод - перевірка на краю.
Ідемпотентність платежів: ключ на'userId + amount + currency + purpose'.
ETA-прозорість: шлюз додає статуси і причини відмов (не коди PSP).

12) Політики крос-регіонів і комплаєнс

Geo-фільтри: білі/чорні списки країн, вікові обмеження, IP-рейнджі.
Дані резидентів: маршрутизація в регіональні кластери (GDPR/локальні закони).
Логи і TTL: зберігання по регіонах, автоматична анонімізація.

13) Приклади конфігурацій

13. 1 NGINX (маршрутизація + ліміт + хедери)

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) Чек-листи

Перед релізом маршруту

• Схема автентифікації (JWT/JWKS, ключі, TTL кешу).
• Таймаути/ретраї/ідемпотентність налаштовані.
• Ліміти: per-IP, per-key, per-route; Квоти партнерів.
• Валідація схеми запитів/відповідей.
• Логи і трасування з'trace-id', маски PII.
• SLO/алерти і дашборд.
• Гео-правила/комплаєнс/вік перевірені.

Операції та платежі

• Смарт-роутинг PSP: правила, пріоритети, фейловер.
• Same-method перевіряється на краю.
• Прозорі статуси і коди помилок для клієнта (без сирого коду PSP).

Релізи

• Canary/AB і kill-switch, план відкату.
• Shadow-трафік на нову версію, порівняння метрик.
• Навантажувальне тестування і p95 цілі.

15) Метрики якості (мінімум)

Availability/SLO за маршрутами; error rate 5xx/4xx.
Latency p50/p95/p99 (зовнішня і внутрішня).
Retry/timeout/circuit події (рівень шуму).
Cache hit-ratio і економія RPS.
Rate-limit hits і відкинуті запити.
PSP-routing KPIs: успіхи, TtW, відсоток фейловера, комісія.

16) Анти-патерни

Один загальний ліміт «на все».
«Миттєві» ретраї без джиттера (посилення шторму).
Довіра до'X-Forwarded-For'без нормалізації і списку довірених проксі.
Тверді таймаути без урахування p95 (помилкові спрацьовування).
Жорсткі трансформації, що ламають сумісність.
Логи з PII/PAN/секретами.
Змішування внутрішнього і зовнішнього API під одним доменом/політикою.

17) Шаблони відповідей і помилки (microcopy)

429 Too Many Requests: "Досягнуто ліміт запитів. Повторіть через N секунд або збільште квоту в кабінеті партнера"

401/403: "Токен недійсний/закінчився. Виконайте вхід заново"

408/504: "Сервіс відповідає довше очікуваного. Запит прийнятий не був"

Idempotency-conflict: "Запит з таким Idempotency-Key вже оброблений (статус: успіх/відмова)"

18) Процес впровадження (за кроками)

1. Модель маршрутів: карта доменів/шляхів/регіонів.
2. Політики безпеки: TLS/mTLS, WAF, authN/Z, ключі/JWKS.
3. Надійність: таймаути, ретраї, idempotency, circuit-breaker.
4. Спостережуваність: логи/метрики/трейси, кореляція.
5. Кеш/перф: edge/micro-cache, компресія, конект-пули.
6. Платіжний роутинг: правила, тести, моніторинг.
7. Релізи: canary/shadow, kill-switch, план відкату.
8. Комплаєнс/гео: фільтри країн, зберігання даних, вік.

Підсумкова шпаргалка

Строгий периметр (TLS/mTLS, WAF, ліміти) + керований трафік (ретраї, circuit, canary).
Валідація і трансформації на краю → менше дефектів «всередині».
Спостережуваність з trace-id і масками PII - не опція, а стандарт.
Смарт-роутинг платежів і комплаєнс-гео - критичні для iGaming.
Версіонування і політика деприкацій - передбачуваність для партнерів.