API şlýuzy we marşrut

1) Arhitekturada API-şlýuzyň roly

• gelýän traffigi kabul edýär (HTTP/HTTP2/HTTP3, WebSocket, gRPC);
• düzgünleri boýunça ugrukdyrýar (host/path/headers/method/query/geo/agram/saglyk);
• geçiş syýasatlaryny ulanýar: tassyklamak/ygtyýarlandyrmak, rate limiting, WAF, CORS, kesmek;
• transformasiýalary ýerine ýetirýär (sözbaşylaryň/jisimleriň kadalaşmagy, gRPC, JSON, GraphQL stitching);
• durnuklylygy üpjün edýär (timeouts, retries, circuit-breaker, outlier detection);
• syn edilmegi we billing (loglar, metrikler, ýollar, kwotalar);
• içerki topologiýany izolirleýär (service mesh, hususy hyzmatlar).

Köplenç jübütlerde ulanylýar: Edge/API-Gateway + Ingress/Mesh (Envoy/Istio/Linkerd) - birinjisi daşary syýasaty çözýär, ikinjisi - gündogar-günbatar.

2) Nusgawy topologiýalar

Bitewi global şlýuz (CDN/edge POP → L7 gateway → hyzmatlar) - ýönekeý, merkezleşdirilen syýasatçylar.
Sebit şlýuzlary (per-region) + geo/gizlinlik boýunça akylly marşrut.
Multi-tenant: bölünip berlen marşrutlar/subtomenler/açarlar, kärendeçi üçin kwotalar we çäklendirmeler.
Hybrid: on-prem + cloud, private link/peering, API şlýuzynyň aňyrsynda hususy yzlar.

3) Marşrut düzgünleri L7

• Host/Path: `api. example. com` → `/v1/orders/`.
• Headers: `X-Client`, `X-Region`, `User-Agent`, `Accept`.
• Method/Content-Type: JSON/Proto/GraphQL.
• Query/Fragment: seresaplylyk bilen - kese/wariantlara täsir edýär.
• Geo/Latency: Iň ýakyn ROR/sebit, zaýalananda faýlower.
• Weighted/Canary: 90/10, 50/50, sticky cookie.
• Session affinity: açar/belgi boýunça hash-based (ulaldylanda seresap).

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) Teswirnamalar we laýyklyk

REST/JSON - defolt, müşderileri tassyklamak/döretmek üçin OpenAPI-ni beýan ediň.
gRPC - HTTP/2 üstünde binar Proto; daşarky müşderiler üçin gRPC-JSON transcoding.
GraphQL - hyzmatlary jemleýär; perimetrde soraglaryň complexity/çuňlugyna gözegçilik ediň.
WebSocket/SSE - iki taraplaýyn/push; sticky we timeouts.
HTTP/2/3 (QUIC) - multiplekslemek/çalt başlamak; WAF/proxy bilen laýyklygyny barlaň.

5) Howpsuzlyk: tassyklamak we ygtyýarlandyrmak

5. 1 Ulag

TLS 1. 2 + perimetrde, HSTS, OCSP stapling, PFS.
mTLS B2B/içerki API we maşyn-maşyn üçin.
IP allowlist/denylist, geo-çäklendirmeler.

5. 2 Amaly dereje

OAuth2/OIDC: JWT bearer-tokenleri, goly/ekspirasiýany/diňleýjini barlamak.
NMAS/gollar: senesi + kanonlaşdyrylan setiri + goly (AWS-meňzeş) - çalyşmakdan, gaýtalamakdan goramak (nonce/wagt penjiresi).
API açarlary: diňe kesgitleýji hökmünde; hukuklar - RBAC/ABAC/satyn alyş arkaly.
CORS: aç-açan allow-origin, pre-flight kesh.
WAF: alamatlar (OWASP API Top 10), anormallik, bot goragy, rekursiw JSON meýdanlary.
DDoS/Abuse: connection limiting, token-bucket/Leaky bucket, berst + orta tizlik, dinamiki ban.

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

6) Walidasiýa, transformasiýa we gabat gelmek

Shemalar: OpenAPI/JSON-Schema/Protobuf boýunça bedeniň/sözbaşylaryň/parametrleriň tassyklamasy.
Üýtgeşmeler: meýdanlaryň kadalaşmagy, PII maskalanmagy, baglanyşyk sözbaşylarynyň goşulmagy ('traceparent', 'x-request-id').
Wersiýa: 'Header: X-API-Version', prefiksler '/v1 ', çeşme-wersiýa; deprecation policy и Sunset.
Backward-compat: diňe add meýdany; täze wersiýa bolmazdan "döwýän" üýtgeşmelerden gaça duruň.
Idempotency: `Idempotency-Key` для POST; gateway TTL bilen Redis-de açarlary saklaýar.

7) Durnuklylyk: baglanyşyk syýasaty

Timeouts: connect/read/write; akylly defoltlar (mysal üçin, 1s/5s/5s).
Retries: diňe howpsuz we idempotent üçin; jitler, exponential backoff, iň köp synanyşyk.
Circuit breaker: ýalňyşlyk/gizlinlik ýüze çyksa açyň; half-open.
Outlier detection: howuzdan erbet ýagdaýlary aýyrmak.
Bulkhead/bäsdeşlik: bir wagtyň özünde per-route haýyşlaryna çäklendirmeler.
Failover: işjeň/passiw, zonal zaýalanma.
Shadow traffic: deňeşdirmek üçin V2 paralel V1 (jogapsyz) "çal" geçişi.

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

8) Kesmek we öndürijilik

HTTP-кеш: `Cache-Control`, `ETag/If-None-Match`, `Vary`, `stale-while-revalidate`.
Edge-keshler/ROR: Statika we "kesişýän" API (idempotent GET) üçin CDN.
Compression: 'gzip/br' (eýýäm gysylan zady gysmaň).
Request collapsing ("coalescing"): birmeňzeş paralel soraglary birleşdirmek.
Response shaping: meýdanlar/süzgüçler, paginasiýa (cursor-based), ululyk çäkleri.

9) Gözegçilik etmek we peýdalanmak

Метрики: `l7_req_total{route,method,code}`, `latency_ms{p50,p95,p99}`, `upstream_errors`, `retry_count`, `cb_state`, `429_rate`, `quota_usage{tenant}`.
Loglar: gurluş, 'trace _ id/span _ id', 'user _ id/tenant _ id', 'client _ ip'.
Söwda: W3C Trace Context ('traceparent', 'tracestate'), akymlara wagyz ediň.
Audit: kim näme, haýsy hukuklar bilen çagyryldy; duýgur API üçin üýtgemeýän ammar.
SLO/SLA: p99 maksatly, ýalňyşlyk býudjeti; rout derejesi global derejeden has gowudyr.

10) Geçiriş ukybynyň meýilnamasyny dolandyrmak

Quota per-tenant/açar/müşderileriň howzy, min/sagat/günde.
Burst + sustained limitleri; tekizlemek üçin leaky bucket.
Fairness: artykmaç ýüklenende - "ilkinji duşuşan" ýerine fair queuing.
Ileri tutulýan ugurlar: ileri tutulýan we bölünip berlen howuzly ulgamlaýyn/möhüm ugurlar.

11) Üýtgetmeleri dolandyrmak we goýbermek

Canary/Blue-Green: agram ugry; SLO boýunça awtomatiki öňe gidişlik (ýalňyşlyklar/gizlinlik).
Feature gates/backend baýdaklar: sözbaşy/token boýunça goşulýar.
Shadowing/diff-validatorlar: jisimleri/statuslary deňeşdirmek, deltada rugsat bermek.
Nyşanlar: saýlanan domenler/ýollar ('staging. api... '), aýry-aýry açarlar we kwotalar.

12) Konfigurasiýa mysallary

12. 1 NGINX - çäk we nagt pul bilen esasy 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 - tereziler we retralar boýunça marşrut

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 Traefik - midlwarlar we hederler

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

13) Anti-patternler

Hemmeler üçin bir global çäk - "gowy goňşular" "şowhunly" sebäpli ejir çekýärler.
Idempotentlik bolmazdan retraýlar → iki gezek effektler (tölegler, jandarlary döretmek).
'timeout '/' max body size' → ýapyşmak/workerleriň tükenmegi.
Şlýuzda edge syýasatlaryny we işewürlik logikasyny garyşdyrmak (perimetri agyrlaşdyrmak).
Shemalary tassyklamagyň ýoklugy → müşderileriň gowşaklygy we "döwýän" goýberişler.
Ýalaňaç WebSocket, auth/limitleri/idle-taýmyny hasaba almazdan.
Aýlawsyz sözbaşylardaky syrlar; içerki B2B-de mTLS ýoklugy.

14) Game Days (Game Days)

Soraglaryň tupany: barlag limiter/quota, 429-hereket, zaýalanma.
Bir klasteriň ýitmegi: failover/artykmaç agram; SLO kanaryek.
Agyr jogaplar: max body/timeouts; birleşmeleri kesmek.
Sanjymlar/anomaliýalar: WAF düzgünleri, rekursiw JSON gadaganlygy, GraphQL-iň uly çuňlugy.
Tracking şowsuzlygy: 'traceparent' propagandasyny we semplemäni barlamak.
Syrlar: Açarlaryň aýlanmagy/JWKS, bellikleriň gutarmagy, clock-skew kabul edilmegi.

15) Girizmegiň çek-sanawy

• OpenAPI/Proto tarapyndan çap edilen domenler/ýollar/wersiýalar kesgitlenildi.
• TLS/mTLS, HSTS, gizlin dolandyryş we aýlanyş sazlandy.
• Tassyklamak (OIDC/HMAC), RBAC/satyn almak, CORS goşuldy.
• per-tenant çäkleri/kwotalary, adalatly nobatlar, 429-UX.
• Terazi/sözbaşy boýunça ugrukdyryş, kanareýalar we rollback meýilnamasy.
• Syýasatlar timeout/retry/circuit-breaker/outlier.
• Shemalary tassyklamak, üýtgetmek, gizlemek PII.
• Edge-кеш/ETag, coalescing, gzip/br.
• Syn edilişi: metrikler, çukurlar, ýollar, daşbordlar we alertler.
• Runbooks: wakalar, açar aýlanmagy, blok sanawlary, "gara anna".

16) FAQ

Q: API şlýuzy hyzmat haltasyndan nähili tapawutlanýar?
A: Şlýuz - demirgazyk-günorta (daşarky perimetri, aşa syýasatçylar). Mesh - gündogar-günbatar (klaster içindäki baglanyşyk/MTLS/retralar). Köplenç bilelikde ulanylýar.

Q: Nirede satmaly auth: şlýuzda ýa-da hyzmatlarda?
A: Iki dereje: şlýuz - coarse-grained (tassyklama, esasy hukuklar/kwotalar), hyzmat - fine-grained (domen rollary/atributlar).

Q: gRPC-JSON transcoding haçan gerek?
A: Haçan-da içerki gRPC, daşarky bolsa REST/JSON we ýönekeý müşderiler/brauzerler talap edilýär.

Q: Wersiýalaşdyrmak strategiýasyny nädip saýlamaly?
A: Köpçülige açyk API üçin - ýol '/vN '+ depriwasiýa sözbaşylary we uzak aralyk. Içerki üçin - capability-baýdaklar/gabat gelmek shemasy.

17) Netijeler

API şlýuzy diňe bir "proksik" däl, eýsem syýasatyň we durnuklylygyň merkezidir. Dogry marşrut, howpsuzlyk, çäkler, tassyklama we syn etmek goýberilişleriň öňünden aýdylýandygyny we tizligini üpjün edýär. Edge-şlýuzy hyzmat torbasy bilen birleşdiriň, kanareýalary we kwotalary awtomatlaşdyryň, şowsuzlyklary synagdan geçiriň - perimetri çüýşe bokurdak däl-de, tizlendiriji bolar.