Brama i routing API

1) Brama API rola w architekturze

• Akceptuje ruch przychodzący (HTTP/HTTP2/HTTP3, WebSocket, gRPC)
• trasy zgodne z zasadami (host/path/headers/method/query/geo/weight/health);
• stosuje politykę typu end-to-end: uwierzytelnianie/autoryzowanie, ograniczanie stawki, WAF, CORS, buforowanie;
• wykonuje transformacje (normalizacja nagłówków/ciał, gRPC, JSON, GraphQL szwy);
• zapewnia stabilność (timeouts, retries, circuit-breaker, outlier detection);
• zapewnia obserwację i rozliczanie (kłody, mierniki, ślady, kwoty);
• izoluje topologię wewnętrzną (siatka usługowa, usługi prywatne).

Często używane w parach: Edge/API-Gateway + Ingress/Mesh (Envoy/Istio/Linkerd) - pierwszy decyduje o polityce zagranicznej, drugi - wschód-zachód.

2) Typowe topologie

Pojedyncza globalna brama (CDN/edge POP → brama L7 → usługi) - prosta, scentralizowana polityka.
Bramy regionalne (na region) + inteligentne trasy geo/opóźnienia.
Multi-najemca: dedykowane trasy/poddomeny/klucze, kwoty i limity na najemcę.
Hybrid: on-prem + cloud, private link/peering, private backends za bramą API.

3) Zasady routingu L7

• Gospodarz/ścieżka: 'api. przykład. com '→ '/v1/orders/'.
• Nagłówki: 'X-Client', 'X-Region', 'User-Agent', 'Accept'.
• Metoda/rodzaj treści: wyróżnienie JSON/Proto/GraphQL.
• Zapytanie/Fragment: ostrożny - wpływa na pamięć podręczną/warianty.
• Geo/Latency: najbliższy POP/region, awaria pod degradacją.
• Ważony/Kanaryjski: dystrybucja ruchu 90/10, 50/50, lepki przez ciasteczko.
• Powinowactwo sesji: hash-based on key/token (careful when scaling).

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) Protokoły i kompatybilność

REST/JSON - domyślnie, opisz OpenAPI dla walidacji/generacji klienta.
gRPC - Proto binarne nad HTTP/2; w przypadku klientów zewnętrznych należy stosować transkodowanie gRPC-JSON.
GraphQL - usługi agregatów; na obwodzie monitorować złożoność/głębokość zapytań.
WebSocket/SSE - dwukierunkowy/push; rozważyć lepkie i czasowe.
HTTP/2/3 (QUIC) - multipleksowanie/szybki start; Sprawdź zgodność WAF/proxy.

5) Bezpieczeństwo: uwierzytelnianie i autoryzacja

5. 1 Transport

TLS 1. 2 + na obwodzie, HSTS, zszywanie OCSP, PFS.
mTLS dla B2B/internal API i maszyny do maszyny.
Lista dopuszczalna IP/denylista, ograniczenia geograficzne.

5. 2 Warstwa aplikacji

OAuth2/OIDC: żetony na okaziciela JWT, weryfikacja podpisu/wygaśnięcia/odbiorcy.
NMAS/podpisy: data + kanonizowana linia + podpis (AWS-like) - ochrona przed podmianą, powtórzeniem (nonce/time window).
Klucze API: tylko jako identyfikator; prawa - poprzez RBAC/ABAC/zakresy.
CORS: wyraźne pochodzenie zezwolenia, pamięć podręczna przed lotem.
WAF: podpisy (OWASP API Top 10), anomalia, ochrona przed botem, rekursywne pola JSON.
DDoS/Abuse: ograniczenie połączenia, token-wiadro/wyciek wiadra, birst + średnia prędkość, dynamiczne zakazy.

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

6) Walidacja, transformacja i kompatybilność

Schematy: walidacja ciała/nagłówków/parametrów zgodnie z OpenAPI/JSON-Schema/Protobuf.
Transformacje: normalizacja pola, maskowanie PII, dodawanie nagłówków korelacji ("traceparent", "x-request-id').
Wersioning: 'Nagłówek: X-API-Version', przedrostki '/v1 ', wersioning zasobów; Polityka deprecover - Sunset.
Kompat wsteczny: tylko pole dodawane; unikać „łamania” zmian bez nowej wersji.
Idempotencja: „Idempotency-Key” дла POST; brama przechowuje klucze w Redis z TTL.

7) Odporność: Zasady połączenia

Timeouts: connect/read/write; rozsądne niewykonanie zobowiązania (np. 1s/5s/5s).
Ponowne próby: tylko dla bezpiecznego i idempotentnego; jitter, wykładnicze backoff, maksymalne próby.
Wyłącznik: otwarty na błędy/opóźnienia; w połowie otwarte na próbki.
Wykrywanie zewnętrzne - usuwanie złych instancji z puli.
Przegroda/konkurencja: ograniczenia dotyczące jednoczesnych wniosków na jedną trasę.
Awaria: aktywna/pasywna, degradacja strefowa.
Ruch cieni: V2 „szary” biegać równolegle do V1 (nie ma wpływu na odpowiedź) dla porównania.

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

8) Buforowanie i wydajność

HTTP-kykeniczne: 'Cache-Control', 'ETag/If-None-Match', 'Vary', 'stale-while-revalidate'.
Bufory krawędziowe/POP: CDN dla API statycznych i buforowanych (idempotent XT).
Kompresja: 'gzip/br' (nie kompresuj już sprężonego).
Zawalenie żądania („koalescing”): połączenie identycznych żądań równoległych.
Kształtowanie odpowiedzi: pola/filtry, kursor, limity rozmiarów.

9) Obserwowalność i działanie

Метрика: 'l7 _ req _ total {route, method, code}', 'latency _ ms {p50, p95, p99}', 'upstream _ errors',' retry _ count', 'cb _ state', '429 _ rate', 'quota _ usage {tenant}'.
Dzienniki: strukturalne, z 'trace _ id/span _ id',' user _ id/tenant _ id', 'client _ ip'.
Ślady: W3C Trace Context („traceparent”, „tracestate”), rozmnażają się w górę rzeki.
Audyt: kto spowodował co, z jakimi prawami; niezmienne sklepy dla wrażliwych API.
SLO/SLA: cel p99, budżet błędu; poziom korzeniowy jest lepszy niż poziom globalny.

10) Zarządzanie planem przepustowości

Kwota na najemcę/klucz/pulę klientów, w min/godzinę/dzień.
Pęknięcie + trwałe limity; nieszczelne wiadro do wygładzania.
Sprawiedliwość: gdy przeciążone - uczciwe kolejki zamiast „pierwszy napotkany”.
Priorytety: trasy systemowe/krytyczne z priorytetowymi i dedykowanymi pulami.

11) Zarządzanie zmianami i wydania

Kanaryjski/niebiesko-zielony: trasa wagi; automatyczne zaliczki na SLO (błędy/opóźnienia).
Bramki funkcyjne/flagi pleców: włącz za pomocą nagłówka/tokena.
Walidatory cieniowania/różnicowania: porównanie ciał/statusów, tolerancje delta.
Etapowanie: przypisane domeny/ścieżki ("staging. api... "), poszczególne klucze i kwoty.

12) Przykłady konfiguracji

12. 1 NGINX - limit podstawowy i brama pamięci podręcznej

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 Wysłannik - bilans i przekaźnik

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 - oprogramowanie pośrednie i nagłówki

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

13) Anty-wzory

Jeden globalny limit dla wszystkich - „dobrzy sąsiedzi” cierpią z powodu „hałasu”.
Przekłady bez idempotencji → duplikaty efektów (płatności, tworzenie podmiotów).
Ignorowanie 'timeout '/' max body size' → wisi/wyczerpuje pracowników.
Mieszanie polityki krawędzi i logiki biznesu w bramie (ważenie obwodu).
Brak walidacji programów → kruchość klientów i „łamanie” wydań.
Nagi WebSocket z wyłączeniem auth/limitów/bezczynności.
Sekrety w nagłówkach bez rotacji; brak mTLS w B2Bs wewnętrznym.

14) Test playbooks (Dni gry)

Burza wniosków: ogranicznik/limit kontrolny, 429-zachowanie, degradacja.
Utrata jednej gromady: niepowodzenie/redystrybucja masy ciała; Kanarki SLO.
Odpowiedzi ważone: max body/timeouts; odcięcie stawów.
Wstrzyknięcia/anomalie: zasady WAF, rekurencyjne hamowanie JSON, duże głębokości GraphQL.
Ślad nie sprawdził rozmnażania i pobierania próbek.
Sekrety: rotacja klucza/JWKS, wygaśnięcie tokena, tolerancja zegara-skew.

15) Lista kontrolna wdrażania

• Domeny/ścieżki/wersje zdefiniowane, OpenAPI/Proto opublikowane.
• Konfigurowane są TLS/mTLS, HSTS, secret management i rotation.
• Uwierzytelnianie (OIDC/HMAC), RBAC/zakresy, włączony CORS.
• Limity/kwoty na najemcę, sprawiedliwe kolejki, 429-UX.
• Routing wagi/nagłówka, plan kanaryjski i zwrot.
• Polityka timeout/retry/circuit-breaker/outlier.
• Zatwierdzanie programów, transformacje, maskowanie PII.
• Krawędź-ке,/ETag, koalescing, gzip/br.
• Obserwowalność: mierniki, kłody, tory, deski rozdzielcze i wpisy.
• Książki startowe: incydenty, rotacja kluczy, listy blokowe, Czarny Piątek.

16) FAQ

P: Czym różni się brama API od siatki serwisowej?
Odp.: Gateway - północ-południe (obwód zewnętrzny, polityka końcowa). Siatka - wschód-zachód (łączność wewnątrzmaciczna/MTLS/retrai). Często używane razem.

P: Gdzie wdrożyć auth: w bramie lub usługach?
Odp.: Oba poziomy: brama - gruboziarnista (uwierzytelnianie, podstawowe prawa/kwoty), usługa - drobnoziarnista (role/atrybuty domeny).

P: Kiedy potrzebne jest transkodowanie gRPC-JSON?
Odp.: Kiedy wewnętrzny gRPC, i na zewnątrz wymaga REST/JSON i prostych klientów/przeglądarek.

P: Jak wybrać strategię wersioning?
Odp.: Dla publicznych interfejsów API - ścieżka '/vN' + nagłówki deprywacji i długie nakładanie się. W przypadku systemu wewnętrznego - flagi zdolności/kompatybilności.

17) Kwoty całkowite

Brama API jest nie tylko serwerem proxy, ale centrum polityki i odporności. Właściwa trasa, bezpieczeństwo, ograniczenia, walidacja i obserwowalność zapewniają przewidywalność i szybkość zwolnień. Połączyć bramę krawędzi z siatką serwisową, zautomatyzować kanarki i kontyngenty, awarie testów - a obwód stanie się akceleratorem, a nie wąskim gardłem.