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

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

• იღებს შემომავალი ტრაფიკს (HTTTP2/HTTP3, WebSocket, gRPC);
• როუტერი წესების მიხედვით (host/path/headers/method/query/geo/წონა/ჯანმრთელობა);
• იყენებს სრულ პოლიტიკას: ავთენტიფიკაცია/ავტორიზაცია, საბაზრო ლიმიტი, WAF, CORS, კაშხალი;
• ასრულებს ტრანსფორმაციებს (სათაურების/ორგანოების ნორმალიზება, gRPC, JSON, GraphQL stitching);
• უზრუნველყოფს სტაბილურობას (timeouts, retries, circuit-breaker, outlier detection);
• იძლევა დაკვირვებას და ბილინგს (ლოგოები, მეტრიკა, კვოტები, კვოტები);
• იზოლირებს შიდა ტოპოლოგიას (მომსახურება mesh, პირადი მომსახურება).

ხშირად გამოიყენება წყვილში: Edge/API-Gateway + Ingress/Mesh (Envoy/Istio/Linkerd) - პირველი წყვეტს საგარეო პოლიტიკას, მეორე - East-west.

2) ტიპიური ტოპოლოგია

ერთი გლობალური კარიბჭე (CDN/edge POP - L7 gateway (მომსახურება) - უბრალოდ, ცენტრალიზებული პოლიტიკოსები.
რეგიონალური კარიბჭეები (per-region) + ჭკვიანი მარშრუტი გეო/ლატენტობისთვის.
Multi-tenant: გამოყოფილი მარშრუტები/ქვე-შეცვლა/გასაღებები, კვოტები და მოიჯარე შეზღუდვები.
Hybrid: on-prem + cloud, პირადი ლინკი/peering, კერძო ზურგჩანთები API კარიბჭის მიღმა.

3) მარშრუტიზაციის წესები L7

• Host/Path: `api. example. com` → `/v1/orders/`.
• Headers: `X-Client`, `X-Region`, `User-Agent`, `Accept`.
• Method/შინაარსის ტიპი: JSON/Proto/GraphQL განსხვავება.
• Query/Fragment: ფრთხილად - გავლენას ახდენს ქეში/ვარიანტებზე.
• Geo/Latency: უახლოესი ROP/რეგიონი, failover დეგრადაციის დროს.
• Wighted/Canary: ტრაფიკის განაწილება 90/10, 50/50, ქუქი-ფაილები.
• Session affinity: hash-bashed გასაღები/docen (სისუფთავე მასშტაბის დროს).

yaml nginx. ingress. kubernetes. io/canary: "true"
nginx. ingress. kubernetes. io/canary-weight: "10" # 10% traffic to new backend

yaml match: { prefix: "/orders", headers: [{name: "X-Experiment", exact_match: "new"}] }
route: { cluster: orders-v2 }

4) ოქმები და თავსებადობა

REST/JSON - ნაგულისხმევი, აღწერეთ OpenAPI მომხმარებლების სავალდებულო/გამომუშავებისთვის.
GRPC - ორობითი პროტო HTTP/2 თავზე; გარე კლიენტებისთვის გამოიყენეთ gRPC-JSON გადარიცხვა.
GraphQL - აერთიანებს მომსახურებებს; პერიმეტრზე გააკონტროლეთ შეკითხვა/სიღრმე.
WebSocket/SSE - ორმხრივი/windows; გაითვალისწინეთ sticky და timeouts.
HTTP/2/3 (QUIC) - მულტიპლექსაცია/სწრაფი დასაწყისი; შეამოწმეთ თავსებადობა WAF/მარიონეტთან.

5) უსაფრთხოება: ავთენტიფიკაცია და ავტორიზაცია

5. 1 ტრანსპორტი

TLS 1. 2 + პერიმეტრზე, HSTS, OCSP stapling, PFS.
mTLS V2V/შიდა API და მანქანებისთვის.
IP allowlist/denylist, გეო შეზღუდვები.

5. 2 გამოყენებითი დონე

OAuth2/OIDC: JWT bearer ნიშნები, ხელმოწერის/ექსპორტი/აუდიტორია.
NMAS/ხელმოწერები: თარიღი + კანონიზებული სტრიქონი + ხელმოწერა (AWS) - დაცვა ჩანაცვლებისგან, გამეორებისგან (nonce/time ფანჯარა).
API გასაღებები: მხოლოდ როგორც იდენტიფიკატორი; უფლებები - RBAC/ABAC/ოფისების საშუალებით.
CORS: აშკარა allow-origin, pre-flight ქეში.
WAF: ხელმოწერები (OWASP API Top 10), ანორმალია, ბოტი დაცვა, რეკურსიული JSON ველები.
DDoS/Abuse: კავშირი შეზღუდული, ტოკენ-ბუკეტი/ლეიკი ბუკეტი, ბერსტი + საშუალო სიჩქარე, დინამიური ბანი.

yaml plugins:
- name: oidc config: { issuer: "...", client_id: "...", client_secret: "...", scopes: ["orders. read"] }
- name: rate-limiting config: { minute: 600, policy: local }

6) ვალიდაცია, ტრანსფორმაცია და თავსებადობა

სქემები: სხეულის/სათაურების/პარამეტრების შესაბამისობა OpenAPI/JSON-Schema/Protobuf.
ტრანსფორმაციები: ველების ნორმალიზაცია, PII- ის შენიღბვა, კორელაციის სათაურების დამატება ('traceparent', 'x-request-id').
ვერსია: 'Header: X-API-Version', პრეფიქსი '/v1 ', რესურსების ვერსია; deprecation policy и Sunset.
Backward compat: მხოლოდ add ველი; თავიდან აიცილეთ „გატეხილი“ ცვლილებები ახალი ვერსიის გარეშე.
Idempotency: `Idempotency-Key` для POST; gateway ინახავს გასაღებებს Redis- ში TTL- ით.

7) სტაბილურობა: კავშირების პოლიტიკა

Timeouts: connect/read/write; გონივრული ნაგულისხმევი (მაგალითად, 1s/5s/5s).
Retries: მხოლოდ უსაფრთხო და idempotent; jitter, exponential backoff, მაქსიმალური მცდელობები.
Circuit breaker: გახსნა შეცდომების/ლატენტობის დროს; ჰალფ-ღია ნიმუშებისთვის.
Outlier detection: აუზიდან ცუდი ინსტანციის ამოღება.
Bulkhead/კონკურენცია: per-route- ის ერთდროული მოთხოვნების შეზღუდვები.
Failover: აქტიური/პასიური, ზონალური დეგრადაცია.
Shadow traffic: შედარებისთვის „ნაცრისფერი“ V2 პროგონი V1- ის პარალელურად (პასუხზე გავლენის გარეშე).

yaml circuit_breakers:
thresholds:
- priority: DEFAULT max_connections: 1024 max_pending_requests: 2048 max_retries: 3

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

HTTP-кеш: `Cache-Control`, `ETag/If-None-Match`, `Vary`, `stale-while-revalidate`.
Edge-keshi/ROR: CDN სტატიკისთვის და „შეშლილი“ API (idempotent GET).
Compression: 'gzip/br' (არ შეკუმშოთ უკვე შეკუმშული).
Request collapsing („coalescing“): იდენტური პარალელური მოთხოვნების გაერთიანება.
Response shaping: ველები/ფილტრები, pagination (cursor-based), ზომების ლიმიტები.

9) დაკვირვება და ექსპლუატაცია

Метрики: `l7_req_total{route,method,code}`, `latency_ms{p50,p95,p99}`, `upstream_errors`, `retry_count`, `cb_state`, `429_rate`, `quota_usage{tenant}`.
Logs: სტრუქტურული, s 'trace _ id/spank _ id', 'user _ id/tenant _ id', 'client _ ip'.
Traces: W3C Trace Context ('traceparent', 'tracestate'), გაფუჭება.
აუდიტი: ვინ გამოიწვია რამე, რა უფლებებით; მგრძნობიარე API- სთვის უცვლელი საცავი.
SLO/SLA: მიზნობრივი p99, შეცდომების ბიუჯეტი; ვარდების დონე უკეთესია ვიდრე გლობალური.

10) გამტარუნარიანობის გეგმის მართვა

É ta per-tenant/გასაღები/კლიენტების აუზი, მინის/საათში/დღეში.
Burst + sustained limites; leaky bucket გასწორებისთვის.
Fairness: გადატვირთვის დროს - „პირველი შეხვედრის“ ნაცვლად.
პრიორიტეტები: სისტემური/კრიტიკული მარშრუტები პრიორიტეტული და გამოყოფილი ტყვიებით.

11) ცვლილებებისა და გამოშვების მენეჯმენტი

Canary/Blue-Green: წონის მარშრუტი; ავტომატური წინსვლა SLO (შეცდომები/ლატენტობა).
Feature gates/უკანა დროშები: ჩართვა სათაურით/ნიშნით.
Shadowing/შემფასებლები: ორგანოების/სტატუსის შედარება, დელტას დაშვება.
Stagings: გამოყოფილი დომენები/ბილიკები ('staging. ap... '), ინდივიდუალური გასაღებები და კვოტები.

12) კონფიგურაციის მაგალითები

12. 1 NGINX - ძირითადი gateway ლიმიტით და ქეშით

nginx map $http_x_request_id $reqid { default $request_id; }

limit_req_zone $binary_remote_addr zone=perip:10m rate=10r/s;

server {
listen 443 ssl http2;
server_name api. example. com;

security add_header Strict-Transport-Security "max-age = 31536000" always;

location /v1/ {
limit_req zone=perip burst=30 nodelay;
proxy_set_header X-Request-ID $reqid;
proxy_set_header Authorization $http_authorization;
proxy_connect_timeout 1s;
proxy_read_timeout 5s;

proxy_cache api_cache;
proxy_cache_valid 200 10s;
proxy_cache_use_stale error timeout updating;
proxy_pass http://orders-v1;
}
}

12. 2 Envoy - მარშრუტიზაცია წონით და ჭიდაობით

yaml routes:
- match: { prefix: "/orders" }
route:
weighted_clusters:
clusters:
- name: orders-v1 weight: 90
- name: orders-v2 weight: 10 retry_policy:
retry_on: "5xx,reset,connect-failure"
num_retries: 2 per_try_timeout: 2s

12. 3 ტრეფიკი - მიდლვარი და ჰედერი

yaml http:
middlewares:
secHeaders:
headers:
stsSeconds: 31536000 contentTypeNosniff: true routers:
api:
rule: "Host(`api. example. com`) && PathPrefix(`/v1`)"
service: svc-orders middlewares: ["secHeaders"]

13) ანტი შაბლონები

ერთი გლობალური ზღვარი ყველასთვის - „კარგი მეზობლები“ განიცდიან „ხმაურიანი“ გამო.
Retrai idempotence - ეფექტების დუბლი (გადახდა, ერთეულების შექმნა).
"Timeout '/' max body size '- ის უგულებელყოფა/ვორკერების ამოწურვა.
edge პოლიტიკის და ბიზნეს ლოგიკის შერევა კარიბჭეში (პერიმეტრის სიმძიმე).
სქემების მიზანშეწონილობის არარსებობა არის მომხმარებელთა სისუსტე და „გატეხილი“ გამოშვებები.
შიშველი WebSocket, auth/limits/idle ტაიმის გამოკლებით.
საიდუმლოებები სათაურებში როტაციის გარეშე; MTLS- ის არარსებობა შიდა B2B- ში.

14) Playbooks (Game Days)

მოთხოვნის ქარიშხალი: limiter/èta შემოწმება, 429 ქცევა, დეგრადაცია.
ერთი მტევნის დაკარგვა: failover/ჭარბი წონა; SLO კანარეები.
მძიმე პასუხები: max body/timeouts; ნაერთების მოჭრა.
ინექციები/ანომალიები: WAF წესები, რეკურსიული JSON აკრძალვა, დიდი GraphQL სიღრმე.
ტრეკერის უკმარისობა: 'traceparent' პროპაგანდისა და ნიმუშების შემოწმება.
საიდუმლოებები: გასაღების როტაცია/JWKS, ტოქსინების გადინება, წვდომის დაშვება.

15) განხორციელების სია

• განსაზღვრულია დომენები/ბილიკები/ვერსიები, გამოქვეყნებულია OpenAPI/Proto.
• TLS/mTLS, HSTS, საიდუმლო მენეჯმენტი და როტაცია.
• ავთენტიფიკაცია (OIDC/HMAC), RBAC/CORS.
• ლიმიტები/კვოტები per-tenant, სამართლიანი ხაზები, 429-UX.
• წონის/სათაურების მარშრუტიზაცია, კანარის გეგმა და rollback.
• პოლიტიკოსები Timeout/retry/circuit-breaker/outlier.
• სქემების, ტრანსფორმაციის, PII- ის შენიღბვა.
• Edge-кеш/ETag, coalescing, gzip/br.
• დაკვირვება: მეტრიკა, ლოგოები, ბილიკები, დაშბორდები და ალერტები.
• Runbooks: ინციდენტები, გასაღების როტაცია, ბლოკის ფურცლები, „შავი პარასკევი“.

16) FAQ

Q: როგორ განსხვავდება API კარიბჭე თვის მომსახურებისგან?
A: კარიბჭე - ჩრდილოეთ სამხრეთი (გარე პერიმეტრი, პოლიტიკის გავლით). Mesh - East west (interclaster კავშირი/MTLS/retrai). ხშირად ერთად გამოიყენება.

Q: სად უნდა გაყიდოთ aut: კარიბჭეში ან სერვისებში?
A: ორივე დონე: კარიბჭე - coarse-grained (ავთენტიფიკაცია, ძირითადი უფლებები/კვოტები), მომსახურება - fine-grained (აფეთქების ღუმელის როლები/ატრიბუტები).

Q: როდის გჭირდებათ GRPC-JSON გადაცემა?
A: როდესაც შიდა gRPC და გარედან საჭიროა REST/JSON და მარტივი მომხმარებლები/ბრაუზერები.

Q: როგორ ავირჩიოთ ვერსიის სტრატეგია?
A: საზოგადოებრივი API- სთვის - გზა '/vN '+ ჩამორთმევის სათაურები და გრძელი overlap. საშინაო - კაპიტალური დროშები/თავსებადობის სქემა.

17) შედეგები

API კარიბჭე არ არის მხოლოდ პროქსი, არამედ პოლიტიკისა და სტაბილურობის ცენტრი. სწორი მარშრუტიზაცია, უსაფრთხოება, ლიმიტები, შესაბამისობა და დაკვირვება იძლევა პროგნოზირებას და გამოცემების სიჩქარეს. დააკავშირეთ edge კარიბჭე სერვისის ჩანთასთან, ავტომატურად გადაიტანეთ კანაფები და კვოტები, შეამოწმეთ წარუმატებლობები - და პერიმეტრი გახდება თქვენი ამაჩქარებელი და არა ბოთლის კისერი.