API-шлюз жана багыттоо

1) архитектура API-шлюз ролу

• Суроо-талаптарды маршруттайт (жол менен/хедерам/гео/салмагы/версиясы).
• периметри коргойт (TLS/mTLS, WAF, DDoS, rate limits, authN/Z).
• Трафикти башкарат (canary/AB, shadow/mirror, circuit breaker, retrailer, таймауттар).
• Стандартташтыруу протоколдору (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' → partner backend; 'Accept: application/grpc'.
Geo-routing: IP/ASN/өлкө (GDPR/жергиликтүү тыюу салуулар, latency).
Weighted/Canary: '90%' эски, '10%' жаңы версия; тез тебүү.
Claim-routing: по `JWT. claims. tier/role/region '(мисалы, жогорку роллер → премиум-лимиттер).
Failover: DPC/булуттар жана PSP ортосундагы актив-актив/актив-пассив.

3) коопсуздук периметри

TLS everywhere: TLS 1. 2 + тышкы, mTLS ичинде (шлюз, кызматтар).
OAuth2/JWT: кол текшерүү, аудит 'exp/nbf/aud/scope', JWKS-айлануу; TTL менен validation кэш.
HMAC: webhooks/төлөмдөр үчүн тел кол.
API ачкычтары: системалык кардарлар үчүн; квоталар/ролдор менен байланыштырат.
WAF: негизги эрежелер (injection, protocol anomalies), дене көлөмү, өлкөлөрдүн дени тизмеси.
DDoS-коргоо: connection limiting, SYN кукилер, IP/ачкыч/end-point боюнча rate-limit.
Zero-Trust: мандат саясаты (SPIFFE/SPIRE, кызматтардын идентификациясы), эң аз укуктар принциби.
Купуялык: Логтордо PII түзөтүү, PAN/IBAN жашыруу, сактоо саясаты.

4) Лимиттер, квоталар жана бурсттардан коргоо

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

• Бурст + sustained (мисалы, '50 rps бурст', '10 rps sustain').
• Retry-Budget жана Slow-Loris коргоо (окуу убактысы).
• өнөктөштөр үчүн күн/ай Quota.

5) Трансформация жана валидация

Нормалдаштырылган аталыштар (trace-id, locale, client-id).
Request/Response-mapping (талаа/коддору, ички атрибуттарды жашыруу).
Shema 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 жана p95> босогосунда атаандаштык сын-пикирлер.

7) Таймауттар, ретрациялар, туруктуулук

Таймауттар: connect/read/write өзүнчө; акылга сыярлык p95-көрсөтмөлөр.
Retrays: idempotent ыкмалары (GET/PUT) c backoff + Jitler; retry-budget.
Idempotency POST: 'Idempotency-Key' + кызмат/шлюз тарабында дедупликация.
Circuit-Breaker: ката/latency; half-open үлгүлөрү.
Bulkhead/Pool-агымдар боюнча обочолонуу.

8) Версия жана шайкештиги

• URI: '/v1/... '(жөнөкөй, бирок "ызы-чуу" каттамдар).
• Header/Content-Negotiation: `Accept: application/vnd. app. v2+json`.
• Feature-желектер/Server capability - азыноолак-өзгөрүүлөр шайкештиги үчүн.

Саясат: SemVer, колдоо терезеси (мисалы, 'v1' = 12-18 ай), деприкация графиги, кеңейтүүлөрдө шайкеш жооптор (талааларды кошуу - сынбайт).

9) байкоо жана сапатын контролдоо

Корреляция: 'traceparent '/' x-request-id' милдеттүү; ылдый ыргытат.
OpenTelemetry: RPS/p50/p95/p99/5xx/4xx метрика, saturation, retry/circuit окуялар.
Logs: структуралык JSON; PII жашыруу; коддору боюнча деңгээлдер.
Tracks Sampling: негизги 5-10% + каталар/жай максаттуу.
SLO/Алерт: жолдор/кардарларга (аптайм, latency, ката).

10) Жол-релиз башкаруу

Blue-Green: DNS/LB которуу.
Canary: салмак үлүшү/сегменттер (аймак, өнөктөш, ролу).
Shadow/Mirror: кардарга жооп жок жаңы нускасына жол көчүрмөсү.
Kill-switch: флаг тез көйгөйлүү апстрим/чичи өчүрүү.

11) акылдуу төлөм багыттоо (iGaming)

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

12) кросс-региондор жана комплаенс саясаты

Гео-чыпкалар: ак/кара өлкөлөрдүн тизмеси, курактык чектөөлөр, 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 кэш).
• Таймауттар/retrailer/ыктымалдуулук орнотулган.
• Чектөөлөр: per-IP, per-key, per-route; өнөктөштөрдүн квоталары.
• Суроо-талаптардын/жооптордун схемасын валидациялоо.
• 'trace-id', PII маска менен Логи жана Tracking.
• SLO/alerty жана dashboard.
• Гео-эрежелер/комплаенс/курагы текшерилген.

Операциялар жана төлөмдөр

• PSP Smart Роутинг: эрежелер, артыкчылыктар, Failover.
• Same-method четинде текшерилет.
• Кардар үчүн ачык статустар жана ката коддору (чийки PSP коду жок).

Релиздер

• Canary/AB жана kill-switch, кайтаруу планы.
• Shadow-traffic боюнча жаңы версия, салыштыруу метрика.
• жүк тестирлөө жана 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, Feylover пайызы, комиссия.

16) Анти-үлгүлөрү

Бир жалпы лимит "бардык".
"Заматта" Джиттер жок Retra (бороон күчөтүү).
Ишеним '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. Байкоо: Логи/метрика/Trace, кореляция.
5. Кэш/перф: edge/micro-cache, компрессия, коннект-пулдар.
6. Төлөм роутинги: эрежелер, тесттер, мониторинг.
7. Релиздер: canary/shadow, kill-switch, кайтаруу планы.
8. Комплаенс/гео: өлкөнүн чыпкалары, маалыматтарды сактоо, жашы.

Жыйынтыктоочу шпаргалка

Катуу периметри (TLS/mTLS, WAF, лимиттер) + башкарылуучу жол (retry, circuit, canary).
Валидация жана трансформация четинде → "ичинде" азыраак кемчиликтер.
trace-id жана PII маскалар менен байкоо - параметр эмес, стандарт.
Акылдуу роутинг төлөмдөр жана комплаенс-гео - iGaming үчүн маанилүү.
Версиялоо жана деприкация саясаты - өнөктөштөр үчүн алдын ала айтуу.