API კარიბჭე და მარშრუტი

1) API კარიბჭის როლი არქიტექტურაში

• ის მარშრუტიზაციას უწევს მოთხოვნებს (გზაზე/ჰედერი/გეო/წონა/ვერსიები).
• იცავს პერიმეტრს (TLS/mTLS, WAF, DDoS, rate limits, authN/Z).
• მართავს ტრაფიკს (canary/AB, shadow/mirror, circuit breaker, retrai, Taimauts).
• სტანდარტიზებულია ოქმები (REST/gRPC/WebSocket), სათაურები, კოდები.
• აკვირდება (ლოგოები, მეტრიკები, ტრეკები, კორელაცია).
• გარდაქმნა და ლიდერია (JSON/XML, ნორმალიზაცია, სკოლა-ვალიდაცია).

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: განაცხადი/grpc'.
Geo-routing: ქვეყნის IP/ASN/მიხედვით (GDPR/ადგილობრივი აკრძალვები, ლატენტობა).
Wighted/Canary: '90% ძველი,' 10% 'ახალი ვერსიისთვის; სწრაფი გამოტოვება.
Claim-routing: по `JWT. claims. tier/role/region '(მაგალითად, high-roller-premium-limites).
Failover: აქტივი/აქტივი-პასიური მონაცემთა ცენტრი/ღრუბლები და PSP.

3) პერიმეტრის უსაფრთხოება

TLS everywhere: TLS 1. 2 + გარეგნობაზე, mTLS შიგნით (კარიბჭე - მომსახურება).
OAuth2/JWT: ხელმოწერის შემოწმება, აუდიტი 'exp/nbf/aud/scope', JWKS როტაცია; ვალიდაციის ქეში TTL- ით.
HMAC: ორგანოების ხელმოწერა webhooks/გადახდებისთვის.
API გასაღებები: სისტემური კლიენტებისთვის; ჩვენ ვუკავშირდებით კვოტებს/როლებს.
WAF: ძირითადი წესები (ინექცია, პროტოკოლის ანომალიები), სხეულის ზომა, ქვეყნების დენის სია.
DDoS დაცვა: შემცირება, SYN ქუქი-ფაილები, 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 დაცვა (კითხვის დრო).
• O ta დღეში/თვე პარტნიორებისთვის.

5) ტრანსფორმაციები და შესაბამისობა

სათაურების Normalize (trace-id, locale, client-id).
Request/Response-mapping (ველები/კოდი, შინაგანი ატრიბუტების დამალვა).
Schema validation (OpenAPI/JSON Schema) გადინების წინ არის 4xxx- ის ადრეული უკმარისობა.
Compression/' Accept-Encoding ', caching (იხ. ქვემოთ).

6) კეშტი და პროდუქტიულობა

Edge ქეში საცნობარო წიგნებისთვის, საზოგადოებრივი მეტამონაცემებისთვის, კონფიგურაციებისთვის (TTL, 'ETag '/' If-None-Match').
მიკრო ქეში 1-5 ცხელ GET- ზე (ამცირებს მწვერვალის დატვირთვას).
Negative-cache მოკლე (404/empty) - ფრთხილად.
Hedging-requests და კონკურენტული რეპლიკების მოთხოვნები p95> ბარიერი.

7) ტაიმაუტები, რეტრაები, სტაბილურობა

Taimauts: კავშირი/read/write ცალკე; გონივრული p95 სახელმძღვანელო.
Retrai: idempotent მეთოდები (GET/PUT) backoff + gitter; retry-budget.
POST Idempotence: 'Idempotency-Key' + დუპლიკაცია მომსახურების/კარიბჭის მხარეს.
Circuit-Breaker: შეცდომები/შეცდომები; ჰალფ-ღია ტესტები.
Bulkhead/აუზის იზოლაცია.

8) ვერსიები და თავსებადობა

• URI: '/v1/... '(უბრალოდ, მაგრამ „ხმაურიანი“ მარშრუტები).
• Header/Content-Negotiation: `Accept: application/vnd. app. v2+json`.
• Feature დროშები/სერვერის კაპიტალიზმი - მცირე ცვლილებების თავსებადობისთვის.

პოლიტიკა: SemVer, დამხმარე ფანჯარა (მაგალითად, 'v1' = 12-18 თვე), დეკრიმინალიზაციის გრაფიკი, შესაბამისი პასუხები გაფართოებების დროს (ველების დამატება - არ არღვევს).

9) დაკვირვება და ხარისხის კონტროლი

კორელაცია: 'traceparent '/' x-request-id' სავალდებულოა; ოსქრვრვ დჲ.
OpenTelemetry: მეტრიკა RPS/p50/p95/p99/5xx/4xx, saturation, retry/circuit მოვლენები.
Logs: სტრუქტურული JSON; შენიღბვა PII; კოდების დონე.
ტრეისების სიმულაცია: ძირითადი 5-10% + სამიზნე შეცდომებისთვის/ნელი.
SLO/ალერტები: მარშრუტებზე/მომხმარებლებზე (აფთიაქი, ლატენცია, შეცდომა).

10) განთავისუფლების ტრაფიკის მენეჯმენტი

Blue-Green: DNS/LB გადართვა.
Canary: წონის წილი/სეგმენტები (რეგიონი, პარტნიორი, როლი).
Shadow/Mirror: ახალი ვერსიისთვის ტრაფიკის ასლი კლიენტისთვის უპასუხოდ.
Kill-switch: დროშა, რომ სწრაფად გამორთოს პრობლემური აფსიდი/ფიჩი.

11) ჭკვიანი გადახდის მარშრუტი (iGaming)

PSP- ის არჩევის წესები: გეო, ვალუტა, თანხა, რისკი, წვდომა, საკომისიო.
Failover PSP: ავტომატური გადასვლა „5xx/timeout“.
Same-method rule: ამაღლება/დასკვნები საწყისი მეთოდის საშუალებით - შემოწმება ზღვარზე.
გადახდების idempotence: გასაღები '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 ქეში).
• Taimauts/retrai/idempotence მორგებულია.
• ლიმიტები: 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) პასუხებისა და შეცდომების შაბლონები (მიკროკოპი)

429 Too Many Requests: "მიღწეულია მოთხოვნის ლიმიტი. გაიმეორეთ N წამის შემდეგ ან გაზარდეთ კვოტა პარტნიორის ოფისში"

401/403: "ტოკენი არასწორია/ამოიწურა. შეავსეთ შეყვანა"

408/504: "მომსახურება პასუხობს მოსალოდნელზე მეტხანს. მოთხოვნა არ მიიღეს"

Idempotence-conflict: „უკვე დამუშავებულია ასეთი Idempotence-Key- ის მოთხოვნა (სტატუსი: წარმატება/უარყოფა).“

18) განხორციელების პროცესი (ნაბიჯებით)

1. მარშრუტების მოდელი: დომენის/ბილიკების/რეგიონების რუკა.
2. უსაფრთხოების პოლიტიკოსები: TLS/mTLS, WAF, authN/Z, გასაღებები/JWKS.
3. საიმედოობა: taimauts, retrai, idempotence, circuit-breaker.
4. დაკვირვება: ლოგოები/მეტრიკა/ტრეისი, კორელაცია.
5. კეში/პერფი: edge/micro-cache, კომპრესია, კონექტის აუზები.
6. გადახდის როუტინგი: წესები, ტესტები, მონიტორინგი.
7. გამოშვებები: canary/shadow, kill-switch, დაბრუნების გეგმა.
8. შესაბამისობა/გეო: ქვეყნების ფილტრები, მონაცემთა შენახვა, ასაკი.

საბოლოო ყალბი ფურცელი

მკაცრი პერიმეტრი (TLS/mTLS, WAF, ლიმიტები) + კონტროლირებადი ტრაფიკი (retrai, circuit, canary).
მისაბმელიანი და ტრანსფორმაცია ზღვარზე ნაკლები დეფექტია „შიგნით“.
Trace-id და PII ნიღბებით დაკვირვება არ არის ვარიანტი, არამედ სტანდარტი.
ჭკვიანი გადახდები და შესაბამისობა გეო - კრიტიკულია iGaming- ისთვის.
ვერსიები და დეფექტების პოლიტიკა პარტნიორებისთვის პროგნოზირებადია.