API şlyuz və marşrutlaşdırma

1) Arxitekturada API şlüzünün rolu

• Sorğuları marşrutlaşdırır (yol/hadedam/geo/çəkisi/versiyası).
• Perimetri qoruyur (TLS/mTLS, WAF, DDoS, rate limits, authN/Z).
• Trafik (canary/AB, shadow/mirror, circuit breaker, retrailer, taymaut) idarə edir.
• Protokolları (REST/gRPC/WebSocket), başlıqları, kodları standartlaşdırır.
• Müşahidə (loqlar, metriklər, izlər, korelasiya).
• Transformasiya və validasiya (JSON/XML, normallaşma, schema-validation).

iGaming üçün bu həm də geo-komplayens (ölkə/yaş kilidi), ödəniş ağıllı routing və kənarda məsuliyyətli oyun siyasəti.

2) Marşrutlaşdırma variantları

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/ölkə (GDPR/yerli qadağalar, latency).
Weighted/Canary: '90%' köhnə, '10%' yeni versiyası; sürətli yuvarlanma.
Claim-routing: по `JWT. claims. tier/role/region '(məsələn, high-roller → premium limitlər).
Failover: DPC/buludlar və PSP arasında aktiv-aktiv/aktiv-passiv.

3) Perimetr təhlükəsizliyi

TLS everywhere: TLS 1. 2 + xaricində, mTLS daxilində (xidmət şluzu).
OAuth2/JWT: imza yoxlama, audit 'exp/nbf/aud/scope', JWKS-rotasiya; TTL ilə validasiya cache.
HMAC: webhooks/ödənişlər üçün telefon imzası.
API açarları: sistem müştəriləri üçün; kvotalarla/rollarla əlaqələndiririk.
WAF: əsas qaydalar (injection, protocol anomalies), bədən ölçüsü, ölkələrin deny siyahısı.
DDoS-qorunması: connection limiting, SYN cookies, IP/açar/end-point rate-limit.
Zero-Trust: mandat siyasətləri (SPIFFE/SPIRE, xidmət kimliyi), ən kiçik hüquqlar prinsipi.
Gizlilik: qeydlərdə PII redaktəsi, PAN/IBAN maskası, saxlama siyasəti.

4) Limitlər, kvotalar və burstlardan qorunma

Модели: token bucket, leaky bucket, fixed/sliding window.
Sərhədləri: per-IP, per-key, per-user, per-route.

• Burst + sustained (məsələn, '50 rps burst', '10 rps sustain').
• Retry-Budget və Slow-Loris qorunması (oxu vaxtı).
• Tərəfdaşlar üçün gündəlik/aylıq Quota.

5) Transformasiya və validasiya

Normalize başlıqlar (trace-id, locale, client-id).
Request/Response-mapping (sahələr/kodlar, daxili atributların gizlədilməsi).
Schema validation (OpenAPI/JSON Schema) proksasiya əvvəl - erkən uğursuzluq 4xx.
Compression/' Accept-Encoding ', caching (aşağıya bax).

6) Caching və Performance

Referans, ictimai metadata, konfiqurasiya üçün Edge-cache (TTL, 'ETag '/' If-None-Match').
Micro-cache 1-5 isti GET (pik yük azaldır).
Negative-cache qısa (404/empty) - diqqətlə.
Hedging-requests və r95> eşik altında replikalar üçün rəqabətli sorğular.

7) Taymaut, retraj, sabitlik

Zaman: connect/read/write ayrıca; ağlabatan p95-işarələr.
Retrajlar: idempotent metodları (GET/PUT) c backoff + jitter; retry-budget.
POST idempotentliyi: 'Idempotency-Key' + servis/şlyuz tərəfində deuplikasiya.
Circuit-Breaker: səhvlər/latency; half-open testlər.
Axınlara görə Bulkhead/Pool-izolyasiya.

8) Version və uyğunluq

• URI: '/v1/... '(sadə, lakin «səs-küy» marşrutları).
• Header/Content-Negotiation: `Accept: application/vnd. app. v2+json`.
• Feature-bayraqlar/server capability - minor-dəyişikliklər uyğunluğu üçün.

Siyasət: SemVer, dəstək pəncərəsi (məsələn, 'v1' = 12-18 ay), deprikasiya cədvəli, uzantılara uyğun cavablar (sahə əlavə - qırılmaz).

9) Müşahidə və keyfiyyətə nəzarət

Korrelyasiya: 'traceparent '/' x-request-id' tələb olunur; aşağı atmaq.
OpenTelemetry: RPS/p50/p95/p99/5xx/4xx metrikası, saturation, retry/circuit hadisələr.
Log: struktur JSON; PII maskalamaq; kodlara görə səviyyələr.
Traces sampling: əsas 5-10% + səhvlər/yavaş hədəf.
SLO/alertlər: marşrutlar/müştərilər (aptaym, latency, səhv).

10) Buraxılış trafikinin idarə edilməsi

Blue-Green: DNS/LB keçid.
Canary: çəki payı/seqmentlər (region, tərəfdaş, rol).
Shadow/Mirror: müştəriyə cavab vermədən yeni versiyaya trafik surəti.
Kill-switch: problem axını/fici tez aradan qaldırılması üçün bayraq.

11) Ödənişlərin smart marşrutlaşdırılması (iGaming)

PSP seçimi qaydaları: geo, valyuta, məbləğ, risk-skor, əlçatanlıq, komissiya.
Failover PSP: '5xx/timeout' zamanı avtomatik keçid.
Same-method rule: orijinal metod vasitəsilə qaytarmalar/nəticələr - kənarda yoxlama.
Ödənişlərin idempotentliyi: açar 'userId + amount + currency + purpose'.
ETA şəffaflığı: Şlyuz status və uğursuzluq səbəbləri əlavə edir (PSP kodları deyil).

12) Kross-region siyasəti və komplayens

Geo-filterlər: ağ/qara ölkə siyahıları, yaş məhdudiyyətləri, IP-reynjlər.
Rezident məlumatları: regional klasterlərə marşrutlaşdırma (GDPR/yerli qanunlar).
Log və TTL: regionlar üzrə saxlama, avtomatik anonimləşdirmə.

13) Konfiqurasiya nümunələri

13. 1 NGINX (marşrutlaşdırma + limit + hederlər)

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) Çek vərəqləri

Marşrutun buraxılmasından əvvəl

• Autentifikasiya sxemi (JWT/JWKS, açarlar, TTL cache).
• Zaman/retraj/idempotentlik özelleştirilmiş.
• Limitlər: per-IP, per-key, per-route; partnyorların kvotaları.
• Sorğu/cavab sxeminin təsdiqlənməsi.
• 'trace-id', PII maskaları ilə qeydlər və izlər.
• SLO/alert və dashboard.
• Geo-qaydalar/complayens/yaş yoxlanılır.

Əməliyyatlar və ödənişlər

• PSP smart routing: qaydalar, prioritetlər, feylover.
• Same-method kənarda yoxlanılır.
• Müştəri üçün şəffaf statuslar və səhv kodları (xam PSP kodu olmadan).

Buraxılışlar

• Canary/AB və kill-switch, geri dönüş planı.
• Shadow trafik yeni versiyası, metrik müqayisə.
• Yük testi və p95 hədəfləri.

15) Keyfiyyət metrikası (minimum)

Availability/SLO marşrutları üzrə; error rate 5xx/4xx.
Latency p50/p95/p99 (xarici və daxili).
Retry/timeout/circuit hadisələr (səs-küy səviyyəsi).
Cache hit-ratio və RPS qənaət.
Rate-limit hits və atılmış sorğular.
PSP-routing KPIs: uğurlar, TtW, faylover faizi, komissiya.

16) Anti-nümunələr

Bir ümumi limit «hər şeyə».
Jittersiz «ani» retrajlar (fırtınanın artması).
Normallaşdırma və etibarlı proxy siyahısı olmadan 'X-Forwarded-For' etibar.
P95 (saxta işə salınma) istisna olmaqla möhkəm vaxtlar.
Uyğunluğu pozan sərt transformasiyalar.
PII/PAN/sirləri olan loqlar.
Bir domen/siyasət altında daxili və xarici API qarışdırın.

17) Cavab şablonları və səhvlər (microcopy)

429 Too Many Requests: "Sorğuların limiti çatıb. N saniyədən sonra təkrarlayın və ya partnyorun ofisindəki kvotanı artırın"

401/403: "Token etibarsızdır. Yenidən daxil olun"

408/504: "Xidmət gözləniləndən daha uzun cavab verir. Sorğu qəbul edilmədi"

Idempotency-conflict: «Belə Idempotency-Key ilə sorğu artıq işlənib (status: uğur/uğursuzluq).»

18) Tətbiq prosesi (addımlarla)

1. Marşrutların modeli: domen/yol/bölgə xəritəsi.
2. Təhlükəsizlik siyasəti: TLS/mTLS, WAF, authN/Z, açarlar/JWKS.
3. Etibarlılıq: taymaut, retrai, idempotency, circuit-breaker.
4. Müşahidə: Logi/Metrics/Traces, Korelation.
5. Cache/perf: edge/micro-cache, sıxılma, konnekt-hovuzlar.
6. Ödəniş marşrutu: qaydalar, testlər, monitorinqlər.
7. Buraxılışlar: canary/shadow, kill-switch, geri dönüş planı.
8. Komplayens/geo: ölkə filtrləri, məlumatların saxlanması, yaş.

Yekun şparqalka

Ciddi perimetr (TLS/mTLS, WAF, limitlər) + idarə olunan trafik (retray, circuit, canary).
→ kənarında validasiya və transformasiya «daxili» daha az qüsurlar.
Trace-id və PII maskaları ilə müşahidə seçimi deyil, standartdır.
Smart-routing ödənişlər və komplayens-geo - iGaming üçün kritik.
Version və deprikasiya siyasəti tərəfdaşlar üçün proqnozlaşdırıla bilər.