API-шлюз жана багыттоо

1) архитектура API-шлюз ролу

• кирген трафикти кабыл алат (HTTP/HTTP2/HTTP3, WebSocket, gRPC);
• эрежелер (host/path/headers/method/query/geo/салмагы/ден соолук);
• аркылуу саясаттарды колдонот: аутентификация/авторизация, rate limiting, WAF, CORS, кэштоо;
• трансформацияларды аткарат (аталыштарды/телефондорду нормалдаштыруу, gRPC, JSON, GraphQL stitching);
• туруктуулукту камсыз кылат (timeouts, retries, circuit-breaker, outlier detection);
• байкоо жана биллинг берет (Логи, метрика, жол, квота);
• ички топологиясын (service mesh, жеке кызматтар) изоляциялайт.

Көбүнчө жупта колдонулат: Edge/API-Gateway + Ingress/Mesh (Envoy/Istio/Linkerd) - биринчиси тышкы саясатты чечет, экинчиси - чыгыш-батыш.

2) Типтүү топологиялар

Бирдиктүү глобалдык шлюз (CDN/edge POP → L7 gateway → кызматтар) - жөнөкөй, борборлоштурулган саясатчылар.
Аймактык шлюздар (per-region) + гео/жашыруун акылдуу багыттоо.
Multi-tenant: бөлүнгөн маршруттар/поддомендер/ачкычтар, квоталар жана ижарачыга лимиттер.
Hybrid: on-prem + cloud, private link/peering, API шлюз үчүн жеке backends.

3) L7 багыттоо эрежелери

• Host/Path: `api. example. com` → `/v1/orders/`.
• Headers: `X-Client`, `X-Region`, `User-Agent`, `Accept`.
• Method/Content-Type: JSON/Proto/GraphQL айырмалоо.
• Query/Fragment: этият - кэш/параметрлерин таасир этет.
• Geo/Latency: Жакынкы РОР/аймак, деградация менен өлтүргөн.
• Weighted/Canary: трафикти бөлүштүрүү 90/10, 50/50, sticky cookie.
• Session affinity: ачкыч/токен боюнча hash-based (кылдаттык менен масштабдоо).

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 үстүндөгү бинардык Proto; тышкы кардарлар үчүн gRPC-JSON transcoding колдонуу.
GraphQL - кызматтарын бириктирет; периметри complexity/сурам тереңдик контролдоо.
WebSocket/SSE - эки тараптуу/бош; sticky жана timeouts эске алуу.
HTTP/2/3 (QUIC) - multiplexing/тез баштоо; WAF/прокси менен шайкештигин текшерүү.

5) Коопсуздук: аутентификация жана авторизация

5. 1 Транспорт

TLS 1. 2 + периметри боюнча, HSTS, OCSP stapling, PFS.
mTLS үчүн B2V/ички API жана машина-машина.
IP allowlist/denylist, гео-чектөөлөр.

5. 2 Колдонмо деңгээл

OAuth2/OIDC: JWT bearer токендери, кол коюу/экспирация/аудиторияны текшерүү.
НМАС/кол тамгалар: дата + канондоштурулган сызык + кол тамга (AWS-окшош) - алмаштыруудан, кайталоодон коргоо (nonce/тайм-терезе).
API ачкычтары: идентификатор катары гана; укуктар - RBAC/ABAC/сатып алуулар аркылуу.
CORS: ачык allow-origin, алдын ала жарык кэш.
WAF: белгилер (OWASP API Top 10), анормалия, бот коргоо, рекурсивдүү JSON талаалар.
DDoS/Abuse: connection limiting, token-bucket/Leaky bucket, берст + орточо ылдамдыгы, динамикалык тыюу.

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

6) валидация, трансформация жана шайкештик

Схемалар: OpenAPI/JSON-схемасы/Protobuf боюнча дененин/аталыштардын/параметрлердин валидациясы.
Трансформация: талааларды нормалдаштыруу, PII маскировкалоо, корреляциялык аталыштарды кошуу ('traceparent', 'x-request-id').
Версиялоо: 'Header: X-API-Version', префикстер '/v1 ', ресурс-версиялоо; deprecation policy и Sunset.
Backward-compat: бир гана add-талаа; жаңы версиясыз "бузуучу" өзгөрүүлөрдөн качыңыз.
Idempotency: `Idempotency-Key` для POST; gateway TTL менен Redis ачкычтарды сактайт.

7) Туруктуулук: байланыш саясаты

Timeouts: connect/read/write; акылга сыярлык дефолттор (мисалы, 1s/5s/5s).
Retries: коопсуз жана idempotent үчүн гана; Jitler, exponential backoff, максималдуу аракет.
Circuit breaker: ката/жашыруун учурда ачуу; үлгүлөрү үчүн half-open.
Outlier detection: Pool жаман учурларда алып салуу.
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 кэш/РОР: статика жана "кэш" API үчүн CDN (Idempotent GET).
Compression: 'gzip/br' (буга чейин кысылып эмес).
Request collapsing ("coalescing"): окшош параллелдүү суроо бириктирүү.
Response shaping: талаалар/чыпкалар, пагинация (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}`.
Логи: структуралык, 'trace _ id/span _ id', 'user _ id/tenant _ id', 'client _ ip'.
Traces: W3C Trace Context ('traceparent', 'tracestate'), агымдарга үгүттөө.
Аудит: ким эмне, кандай укуктар менен чакырды; сезимтал API үчүн өзгөрүлбөс сактоо.
SLO/SLA: p99 максаттуу, жаңылыштык бюджети; роут деңгээл дүйнөлүк караганда жакшы.

10) Өткөрүү планын башкаруу

Quota per-tenant/ачкыч/кардарлардын бассейни, мин/саат/сутка.
Бурст + sustained лимиттери; leaky bucket тегиздөө үчүн.
Fairness: ашыкча жүктөөдө - "биринчи жолуккандардын" ордуна fair queuing.
Артыкчылыктар: артыкчылыктуу жана бөлүнгөн бассейндер менен системалуу/маанилүү маршруттар.

11) Өзгөрүүлөрдү башкаруу жана релиздер

Canary/Blue-Green: салмак багыттоо; SLO боюнча автоматтык жылдыруу (каталар/жашыруун).
Feature gates/backend желектери: аталышы/токен боюнча киргизүү.
Shadowing/дифф-валидаторлор: тел/статустарды салыштыруу, дельта боюнча кабыл алуу.
Тагдыр: бөлүнгөн домендер/жолдор ('staging. api... '), жеке ачкычтар жана квоталар.

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 - тараза жана retraia боюнча багыттоо

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 - Мидлвари жана хедерлер

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

13) Анти-үлгүлөрү

"Жакшы кошуналар", анткени "ызы-чуу" азап - бардык бир глобалдык чектөө.
Идемпотенттүүлүк жок Retry → дубль эффекттери (төлөмдөр, жандыктарды түзүү).
кайдыгер 'timeout '/' max body size' → илинип/чарчап үйрөнчүктөр.
edge-саясат жана бизнес-логика шлюзда аралаштыруу (периметри салмагы).
Схемалардын валидациясынын жоктугу → кардарлардын морт болушу жана "сындыруучу" релиздер.
Жылаңач WebSocket кошпогондо auth/лимиттер/idle-тайм.
Ротациясыз аталыштарда сырлар; жок mTLS ички B2B.

14) Test Playbook (Оюн күндөрү)

Storm суроо: текшерүү limiter/quota, 429-жүрүм-туруму, деградация.
бир кластердин жоготуу: failover/ашыкча салмак; SLO канарейка.
оор жооптор: max body/timeouts; байланыштарды кесип.
Инъекциялар/аномалиялар: WAF эрежелери, рекурсивдүү JSON тыюу салуу, GraphQL чоң тереңдиктер.
Жолдогу ката: 'traceparent' пропагандасын жана семплирлөөнү текшерүү.
Сырлар: ачкычтарды айлантуу/JWKS, Токендердин мөөнөтү бүтөт, Clock-skew кабыл алуу.

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 - чыгыш-батыш (/MTLS/retrains). Көбүнчө чогуу колдонулат.

Q: auth ишке ашыруу үчүн кайда: кулпу же кызмат?
A: Эки деңгээл: шлюз - coarse-grained (аутентификация, негизги укуктар/квоталар), кызматы - fine-grained (домендик ролдор/атрибуттар).

Q: качан gRPC-JSON transcoding керек?
A: Качан ички gRPC жана тышкы REST/JSON жана жөнөкөй кардарлар/браузерлер талап кылынат.

Q: Кантип чыгаруу стратегиясын тандоо керек?
A: Коомдук API үчүн - жол '/vN '+ депривация аталыштары жана узак overlap. Ички үчүн - capability желектери/шайкештик схемасы.

17) Натыйжалары

API-шлюз - жөн гана "проксик" эмес, саясаттын жана туруктуулуктун борбору. Туура багыттоо, коопсуздук, чеги, validation жана байкоо алдын ала жана чыгаруу ылдамдыгын берет. Edge-шлюз менен кызмат баштыгын айкалыштыруу, канареяларды жана квоталарды автоматташтыруу, каталарды сыноо - жана периметр бөтөлкө оозу эмес, сиздин ылдамдаткычыңыз болуп калат.