API дарвоза ва масир

1) Нақши дарвозаи API дар меъморӣ

• Трафики воридшавандаро қабул мекунад (HTTP/HTTP2/HTTP3, Websocket, GRPC)
• хатсайрҳо тибқи қоидаҳо (хост/роҳ/сарлавҳа/усул/дархост/гео/вазн/саломатӣ);
• сиёсати ниҳоӣ татбиқ мешавад: аутентификатсия/авторизатсия, маҳдудкунии меъёрҳо, WAF, CORS, кэш;
• тағиротро иҷро мекунад (ба эътидол овардани сарлавҳаҳо/баданҳо, gRPC↔JSON, дӯзандагии GraphQL);
• суботро таъмин мекунад (танаффус, такрорӣ, схемачӣ, муайянкунии берунӣ);
• мушоҳида ва биллингро медиҳад (гузоришҳо, ченакҳо, изҳо, квотаҳо);
• топологияи дохилиро ҷудо мекунад (фикрию хизматрасонӣ, хадамоти хусусӣ).

Аксар вақт дар ҷуфтҳо истифода мешаванд: Edge/API-Gateway + Ingress/Mesh (Envoy/Istio/Linkerd) - якум сиёсати хориҷиро ҳал мекунад, дуюм - шарқу ғарб.

2) Топологияҳои маъмулӣ

Дарвозаи ягонаи глобалӣ (CDN/edge POP → L7 gateway services) - сиёсати оддӣ, мутамарказ.
Дарвозаҳои минтақавӣ (дар як минтақа) + масири оқилонаи гео/таъхир.
Иҷорагир: хатсайрҳои махсус/субдомайнҳо/калидҳо, квотаҳо ва маҳдудиятҳо барои як иҷорагир.
Гибрид: on-prem + абр, пайванди хусусӣ/пиринг, пуштибони хусусӣ дар паси дарвозаи API.

3) Қоидаҳои масири L7

• Мизбон/Роҳ: 'api. намуна. com '→ '/v1/фармоиш/'.
• Сарлавҳаҳо: 'X-Client', 'X-Region', 'User-Agent', 'Қабул'.
• Усул/Намуди мундариҷа: фарқ кардани JSON/Proto/Graph
• Дархост/фрагмент: бодиққат - ба кэш/вариантҳо таъсир мерасонад.
• Geo/Latency: наздиктарин POP/минтақа, дар ҳолати таназзул қарор нагирифтааст.
• Вазн/Канария: тақсимоти трафик 90/10, 50/50, часпак аз куки.
• Наздикии сессия: ҳаш дар асоси калид/нишона (ҳангоми миқёс бодиққат).

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 - бо нобаёнӣ, Open

GRPC - дуӣ Proto бар HTTP/2; барои муштариёни беруна, транскодингҳои GRPC-JSON-ро истифода баред.
GraphQL - хизматрасониҳои маҷмӯӣ; дар периметр мураккабӣ/умқи дархостҳоро назорат кунед.
Web-Socket/SSE - дуҷониба/тела; часпак ва вақтро ба назар гиред.
HTTP/2/3 (QUIC) - мултиплексинг/оғози тез; Мутобиқати WAF/проксиро тафтиш кунед.

5) Амният: аутентификатсия ва авторизатсия

5. 1 Нақлиёт

TLS 1. 2 + дар периметри, HSTS, stapling OCSP, PFS.
mTLS барои B2B/internal API ва мошин-ба-мошин.
IP allowlist/denylist, маҳдудиятҳои гео.

5. 2 Қабати барнома

OAuth2/OIDC: Нишонаҳои барандаи JWT, имзо/анҷомёбӣ/санҷиши аудитория.
NMAS/имзоҳо: сана + хати канонизатсияшуда + имзо (ба монанди AWS) - муҳофизат аз ивазкунӣ, такрорӣ (равзанаи nonce/time).
Калидҳои API: танҳо ҳамчун идентификатор; ҳуқуқҳо - тавассути RBAC/ABAC/миқёс.
CORS: ба таври возеҳ иҷозат дода мешавад, кэши пеш аз парвоз.
WAF: имзоҳо (OWASP API Top 10), аномалия, муҳофизати бот, майдонҳои рекурсивии JSON.
DD ho 'S/сӯиистифода: маҳдудкунии пайвастшавӣ, сатил сатил/сатил ихроҷ, суръати миёнаи birst + манъи динамикӣ.

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

6) Тасдиқ, тағирот ва мутобиқат

Схемаҳо: тасдиқи бадан/сарлавҳаҳо/параметрҳо аз рӯи Open-API/JSON-Schema/Protobuf.
Тағирот: нормализатсияи майдон, ниқоби PII, илова кардани сарлавҳаҳои коррелятсия ('traceparent', 'x-request-id').
Версия: 'Сарлавҳа: X-API-Version', префиксҳои '/v1 ', нусхабардории захираҳо; сиёсати фарсудашавии ғуруби офтоб.
Қафо-муқоиса: танҳо майдони иловагӣ; аз тағиротҳои "шикастан" бидуни версияи нав канорагирӣ кунед.
Idempotency: 'Idempotency-Key' dlya POST; дарвоза калидҳоро дар Редис бо TTL нигоҳ медорад.

7) Устуворӣ: Сиёсати пайвастшавӣ

Вақтсанҷҳо: пайваст/хондан/навиштан; пешфарзҳои оқилона (масалан, 1с/5с/5с).
Санҷишҳо: танҳо барои бехатар ва бефоида; jitter, бозгашт экспоненсиалӣ, кӯшиши ҳадди аксар.
Қатъи гардиш: кушодани хатогиҳо/ниҳонӣ; барои намунаҳо нисфи кушода.
Муайянкунии берунӣ - ҳолатҳои бадро аз ҳавз хориҷ кунед.
Bulkhead/рақобат: маҳдудиятҳои дархостҳои ҳамзамон барои як маршрут.
Нокомӣ: деградатсияи фаъол/ғайрифаъол, минтақавӣ.
Трафики сояафкан: V2 "хокистарӣ" барои муқоиса бо V1 мувозӣ аст (таъсир ба посух нест).

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

8) Кэшинг ва иҷрои

HTTP-кеш: 'Кэш-Назорат', 'ET' ag/If-None-Match ',' Vary ',' кӯҳна-дар ҳоле ки-revalidate '.
Кэшҳои канорӣ/POP: CDN-ҳо барои API-ҳои статикӣ ва кэшшуда (GET-ҳои idempotent).
Фишурдасозӣ: 'gzip/br' (фишурдаро аллакай фишурда накунед).
Пошхӯрии дархост ("coalescing"): якҷоя кардани дархостҳои параллелии якхела.
Ташаккули ҷавоб: майдонҳо/филтрҳо, курсор, маҳдудиятҳои андоза.

9) Мушоҳида ва амалиёт

Метрикӣ: 'l7 _ req _ total {масир, усул, рамзи}', 'latency _ ms {p50, p95, p99}', 'upstream _ хатогиҳо', 'retry _ count', 'cb _ state', '429 _ rate', 'quota _ usage {иҷорагир}'.
Гузоришҳо: сохторӣ, бо 'trace _ id/span _ id', 'user _ id/renant _ id', 'client _ ip'.
Нишонаҳо: Контексти W3C Trace ('пайгирӣ', 'tracestate'), ба болооб паҳн кунед.
Аудит: кӣ бо кадом ҳуқуқҳо сабаб шуд; мағозаҳои ивазнашаванда барои API-ҳои ҳассос.
SLO/SLA: ҳадафи p99, буҷаи хато; сатҳи реша аз сатҳи ҷаҳонӣ беҳтар аст.

10) Идоракунии нақшаи иқтидор

Квота барои ҳар як иҷорагир/калид/ҳавзи муштариён, дар дақиқа/соат/рӯз.
Таркиш + маҳдудиятҳои пойдор; сатил ихроҷ барои ҳамвор кардан.
Адолат: ҳангоми изофабор - навбати одилона ба ҷои "бори аввал дучор омад".
Афзалиятҳо: хатсайрҳои системавӣ/муҳим бо ҳавзҳои афзалиятнок ва махсус.

11) Идоракунии тағирот ва релизҳо

Канария/кабуд-сабз: масири вазн; пешрафти худкор дар SLO (хатогиҳо/ниҳонӣ).
Дарвозаҳои хусусият/парчамҳои пушти сар: бо сарлавҳа/нишона фаъол кунед.
Валидаторҳои сояафкан/дифф: муқоисаи ҷасадҳо/статусҳо, таҳаммулпазирии дельта.
Марҳила: доменҳо/пайраҳаҳои ҷудошуда ('саҳна. апи... '), калидҳо ва квотаҳои инфиродӣ.

12) Намунаҳои конфигуратсия

12. 1 NGINX - Маҳдудияти асосӣ ва дарвозаи кэш

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 Фиристанда - Масири мувозинат ва хатсайр

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) Анти-намунаҳо

Як лимити ҷаҳонӣ барои ҳама - "ҳамсояҳои хуб" аз сабаби "ғавғо" азият мекашанд.
Бозсозӣ бидуни идемпотенция → эффектҳои такрорӣ (пардохтҳо, эҷоди субъектҳо).
Нодида гирифтани 'вақт '/' андозаи максималии бадан' → коргаронро овезон/хаста мекунад.
Омезиши сиёсатҳои канорӣ ва мантиқи тиҷорат дар дарвоза (вазни периметр).
Набудани тасдиқи схемаҳо → осебпазирии мизоҷон ва нашри "шикастан".
Веб-Socket-и бараҳна, ба истиснои auth/limits/вақти бекорӣ.
Асрори сарлавҳаҳо бе гардиш; mTLS дар B2Bs дохилӣ нест.

14) Китобҳои санҷишӣ (Рӯзҳои бозӣ)

Тӯфони дархостҳо: маҳдудият/квота, 429-рафтор, таназзулро санҷед.
Аз даст додани як кластер: тақсимоти нокомӣ/вазн; Канарейкаҳои SLO.
Ҷавобҳои вазн: максималии бадан/вақт; буридани буғумҳо.
Тазриқ/аномалия: қоидаҳои WAF, ҷилавгирӣ аз рекурсивии JSON, чуқурии калони GraphQL.
Trace натавонист тарғиб ва интихоби "traceparent" -ро тафтиш кунад.
Асрҳо: гардиши калидӣ/JWKS, мӯҳлати тамға, таҳаммулпазирии соат.

15) Рӯйхати назорати амалисозӣ

• Доменҳо/роҳҳо/версияҳои муайяншуда, Open
• TLS/MTLS, HSTS, идоракунии махфӣ ва гардиш танзим карда шудаанд.
• Аутентификатсия (OIDC/HMAC), RBAC/миқёс, CORS фаъол аст.
• Маҳдудиятҳо/квотаҳо барои ҳар як иҷорагир, навбатҳои одилона, 429-UX.
• Масири масир/сарлавҳа, нақшаи канарӣ ва бозгашт.
• сиёсати танаффус/retry/circuit-breaker/outlier.
• Тасдиқи нақша, тағирот, ниқоби PII.
• Edge-kesh/ET jag, coalescing, gzip/br.
• Мушоҳидаҳо: ченакҳо, гузоришҳо, роҳҳо, панелҳо ва огоҳиҳо.
• Китобҳои корӣ: ҳодисаҳо, гардиши калидӣ, рӯйхати блокҳо, Ҷумъаи сиёҳ.

16) FAQ

Савол: Чӣ гуна дарвозаи API аз фикрию хидматрасонӣ фарқ мекунад?
A: Дарвоза - шимол-ҷануб (периметри беруна, сиёсати ниҳоӣ). Mesh - шарқу ғарб (пайвасти intracluster/MTLS/retrai). Аксар вақт якҷоя истифода мешаванд.

Савол: Дар куҷо татбиқ кардани auth: дар дарвоза ё хидматҳо?
A: Ҳарду сатҳ: дарвоза - донаҳои калон (аутентификатсия, ҳуқуқҳои асосӣ/квотаҳо), хизматрасонӣ - ҷарима (нақшҳои домейн/атрибутҳо).

Савол: Кай транскодиринги GRPC-JSON лозим аст?
A: Вақте ки gRPC дохилӣ ва берун аз он REST/JSON ва мизоҷони оддӣ/браузерҳоро талаб мекунад.

Савол: Чӣ гуна як стратегияи версиониро интихоб кардан мумкин аст?
A: Барои API-ҳои оммавӣ - роҳ '/v 'N' + сарлавҳаҳои маҳрумият ва такрори дароз. Барои дохилӣ - қобилияти парчамҳо/схемаи мутобиқат.

17) Натиҷаҳо

Дарвозаи API на танҳо прокси, балки маркази сиёсат ва устуворӣ мебошад. Масири дуруст, амният, маҳдудиятҳо, санҷиш ва мушоҳидаҳо пешгӯӣ ва суръати релизҳоро медиҳанд. Дарвозаи канориро бо торҳои хидматрасонӣ якҷоя кунед, канарейкаҳо ва квотаҳоро автоматӣ кунед, камбудиҳои санҷиш - ва периметр суръатбахшии шумо хоҳад буд, на мушкилот.