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 ішінде (шлюзі, сервистері).
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) Трансформация және валидация

(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» сенімді прокси тізімінсіз және қалыпқа келтірілмеген.
Р95 есепке алынбаған қатты таймауттар (жалған іске қосулар).
Үйлесімділікті бұзатын қатты трансформациялар.
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 үшін өте маңызды.
Нұсқалау және деприкация саясаты - серіктестер үшін болжамдылық.