API ekosystemu

(Sekcja: Ekosystem i sieć)

1) Cele i zasady

• Szybka, przewidywalna integracja (czas do integracji).
• Niezawodność i skalowalność (SLO, QoS, backpressure).
• Bezpieczeństwo i zgodność (minimalne prawa, audyt).
• Ewolucja bez podziałów (wersje, kompatybilność, ficheflagi).

Zasady: umowa pierwsza, minimalizacja danych, idempotencja, domyślna obserwowalność, „dwie prędkości” wydań (rdzeń vs eksperymentalne).

2) Taksonomia API

1. REST/HTTP - synchroniczne operacje CRUD/command, idempotence-key, pagination/cursors.
2. gRPC/QUIC - niskie opóźnienia, strumienie, protokoły binarne.
3. Zdarzenia (Pub/Sub) - zdarzenia domeny ('deposit. „,” wypłata. „,” most. „,” ryzyko. ').
4. Haki internetowe - powiadomienia odwrotne z podpisami i przekładkami.
5. GraphQL (limited) - agregacja odczytuje zmaterializowane sklepy.
6. Administrator/Meta - katalogi, wersje, statusy, klucze, kwoty.

Poziomy dostępu: publiczne (ograniczone metody/odczyty), partnerskie (zakresy i kwoty), wewnętrzne (kontury prywatne).

3) Umowy i systemy

OpenAPI/AsyncAPI/Protobuf IDL jest jednym źródłem prawdy.
Kontrakty na dane - testy zgodności, linery obwodowe, zakaz „łamania” pól bez MAJOR.
Katalogi: aktywa/sieci, PSP/metody, regiony/jurysdykcje, wersje SDK, flagi możliwości.

Minimalna umowa REST (fragment OpenAPI)

yaml openapi: 3. 0. 3 info: { title: Ecosystem Core API, version: "2. 6. 0" }
paths:
/v2/payouts:
post:
operationId: createPayout parameters:
- in: header name: Idempotency-Key required: true schema: { type: string, maxLength: 64 }
requestBody:
required: true content:
application/json:
schema:
$ref: "#/components/schemas/PayoutRequest"
responses:
"202": { $ref: "#/components/responses/Ack" }
"409": { description: "Duplicate (idempotent)" }
components:
schemas:
PayoutRequest:
type: object required: [amount, currency, destination]
properties:
amount:  { type: string, pattern: "^[0-9]+(\\.[0-9]{1,9})?$" }
currency: { type: string, example: "USD" }
destination: { type: string }
metadata: { type: object, additionalProperties: true }

Zdarzenia (AsyncAPI)

yaml asyncapi: 2. 6. 0 info: { title: Ecosystem Events, version: "1. 9. 0" }
channels:
payout. finalized:
subscribe:
message:
name: PayoutFinalized payload:
type: object required: [id, ts, amount, currency, status, signature]
properties:
id: { type: string }
ts: { type: string, format: date-time }
amount: { type: string }
currency: { type: string }
status: { type: string, enum: ["finalized","failed"] }
signature: {type: string} # source signature

4) Wersioning i kompatybilność

SemVer: "MAJOR. DROBNE. PATCH '. MINOR/PATCH - kompatybilny wstecz; MAJOR - równoległe wersje ('/v1 ', '/v2') + adaptery.
Polityka odrzucenia: okno ≥ 90 dni, „dwie linie” wsparcia, automatyczne powiadomienia o umowach.
Flagi funkcji: włączyć/wyłączyć pola/metody według regionu/partnera.
Możliwość negocjacji: deklarowanie wspieranych profili podczas potrząsania rękami.

5) Idempotencja, zamówienia i kursory

Idempotence-Key dla poleceń (utwórz/anuluj), klawiszy TTL ≥ 72 godziny.
Dokładnie raz semantyka za pośrednictwem skrzynki odbiorczej/skrzynki odbiorczej i konsumenta idempotent.
Pagination by cursors: 'next _ cursor', resistance to insertions/deletions.
Sortowanie i filtry są stabilne, wyraźnie udokumentowane.

6) Bezpieczeństwo i zaufanie

mTLS (serwis i usługa), szpilki serc i rotacji kluczy.
OAuth2/OIDC (poświadczenia klienta, JWT z krótkim TTL), PoP/DPoP do wiązania z kanałem.
Podpis webhook (NMAS/wersja/czas klucza), ochrona przed powtarzaniem.
RBAC/ABAC i PoLP: zakresy, org_id/tenant_id, ograniczenia obiektu/działania.
Minimalizacja DLP/PII: zakaz PII w etykietach/dziennikach, tokenizacja identyfikatorów.
Limity stawek i WAF: na org/trasa/region, ochrona przed nadużyciami.

Przykładowa polityka kluczowa (YAML)

yaml auth:
oauth2:
issuer: "https://auth. ecosys"
jwks_uri: "https://auth. ecosys/.well-known/jwks. json"
token_ttl_s: 900 mtls:
required_for: ["internal","partner_p0"]
scopes:
- name: payouts:write
- name: payouts:read
- name: events:subscribe

7) Kwoty, QoS i ciśnienie wsteczne

Klasy QoS: P0 (płatności/most/finalizacja), P1 (produkt), P2 (luzem/archiwum).
Kontyngenty/limity: RPS, concur-requests, bytes/sec, subject/party for events.
Kontrola wstęp: wczesne odrzucenie „drogich” wniosków, ciężki-zapytanie-strażnik.
Backpressure: żetony/kredyty, kolejki z DLQ, retras z jitter.

Polityka kontyngentowa

yaml quotas:
partner_default:
rps: 200 concurrent: 100 webhooks_outbound_rps: 50 p0:
rps: 100 p95_latency_ms: 400

8) Obserwowalność: SLI/SLO, mierniki, ślady

• p95/99 latency беларкретаz, Success Rate, Error budget burn, Queue-lag p95, Freshness webhooks, Delivery success%.
• Zgodność z umową% (schematy/podpisy).
• Webhook retry/dropped%.

SLO: P0 p95 ≤ 400 ms, dostępność ≥ 99. 95%; Dostawa haka p95 ≤ 2 "; Świeżość zdarzeń p95 ≤ 60 ".

Wskaźniki: histogramy opóźnień, kody błędów, rozmiar odpowiedzi, RPS, na najemcę.
Ślady: end-to-end 'trace _ id' (krawędź → gateway → service → DB → event/webhook).
Dzienniki: struktura, bez PII, korelacja przez 'request _ id'.

9) Schematy zwolnienia bez przestojów

Niebiesko-zielony/kanaryjski z bramkami SLO i wytryskiem zewnętrznym.
Schemat-pierwsza ewolucja: tylko dodawanie pól, adaptery dla starych klientów.
Migracje bazy danych zero-przestojów: online DDL, dwukierunkowe konwertery.
Kontrola zmian: timelock, audyt i rejestr zgodności.

10) Katalogi i rejestry

Rejestr API/wersji

sql
CREATE TABLE api_registry(
name TEXT, kind TEXT,      -- rest    grpc    events    webhook version TEXT, status TEXT,   -- active    canary    deprecated    retired slo JSONB, owner TEXT,
PRIMARY KEY (name, version)
);

Katalog wydarzeń

sql
CREATE TABLE event_catalog(
topic TEXT PRIMARY KEY,
schema_version TEXT,
qos TEXT,
retention_days INT,
pii BOOLEAN DEFAULT false
);

Klucze/zakresy

sql
CREATE TABLE api_keys(
key_id TEXT PRIMARY KEY,
org_id TEXT, scopes TEXT[], status TEXT, expires_at TIMESTAMPTZ
);

11) Testowanie i przestrzeganie umów

Testy kontraktowe: generowanie klientów, zatwierdzanie schematów, negative-_cases.
Powtórne testy zdarzeń: odporność na powtarzanie/ponowne zamawianie.
Chaos/Lata-testy: strata/jitter wstrzyknięcia, powolny stor.
Testy bezpieczeństwa: podpis haka, rotacja klucza, ataki powtórne.
Profile wydajności: kolce SLA, gorące trasy, most DA/zależność.

12) Przykłady interfejsów

Haki internetowe (podpis i retrai)

yaml webhooks:
deliveries:
retry:
attempts: 5 backoff_ms: [200, 800, 1600, 3200, 6400]
jitter: true signature:
alg: "HMAC-SHA256"
header: "X-ECO-Signature"
timestamp_header: "X-ECO-Timestamp"
tolerance_s: 300

GraphQL (agregowanie odczytów, tylko do odczytu)

graphql type Query {
payouts(status: [Status!], first: Int!, after: String): PayoutConnection!
}

gRPC (przepływ zdarzeń)

proto service EventStream {
rpc Subscribe(SubscribeRequest) returns (stream Event);
}

13) Procesy i role

Właściciel API - Umowa/Wersja/SLO/Kwota.
Bezpieczeństwo - klucze/podpisy/audyt/DLP.
SRE/Ops - deski rozdzielcze, wpisy, pojemność.
Sukces partnera - wejście na pokład, limity, phicheflags.
Zgodność - jurysdykcje, sankcje, sprawozdawczość.

14) Deski rozdzielcze

Interfejs API rdzenia: opóźnienie/błąd/RPS według trasy i namiotu.
Haki internetowe: dostawa p95, ponowne próby, krople, podpisy.
Wydarzenia: świeżość, opóźnienie, zdrowie konsumentów, DLQ.
Bezpieczeństwo: klucze wygaśnięcia, podpisy, odrzucone żądania.
Zarządzanie: aktywne wersje/deprecacje, kompatybilność umów.

15) Incydenty Playbook

A. Wzrost opóźnienia p95 P0

1. Włącz priorytet P0 i P2-throttle; 2) bramy skali;

2. Przełączanie części odczytu do pamięci podręcznej 4) analiza „gorących” tras.

B. Dostawa kropla z haka

1. Sprawdzanie podpisów/zmiany godzinowej, 2) zwiększanie retras/timeouts,

2. włączyć partie, 4) tymczasowo przełączyć na punkt końcowy pocisku.

C. Kontrakty dryfujące

1. Włącz „tryb ścisły”,

2. powiadomić producenta, 3) zwolnić adapter, 4) pośmiertnie, zaktualizować liniowce.

D. Kompromis klucza/certa

1. Odwołać/obrócić, 2) powtórzyć haki internetowe, 3) audyt, 4) powiadomić partnerów.

E. Powtórzyć/podjąć wybuch

1. Sprawdź Idempotency-Key/TTL, 2) wzmocnić deadup, 3) ograniczyć „hałaśliwe” źródło.

16) Lista kontrolna wdrażania

1. Opisz kontrakty (OpenAPI/AsyncAPI/IDL), w tym lintery i CI.
2. Konfiguracja auth (OAuth2/OIDC, mTLS), podpis haka internetowego, rotacja klucza.
3. Wprowadź limity/QoS/limits, heavy-query-guard i backpressure.
4. Zwiększ obserwowalność: SLI/SLO, tory, deski rozdzielcze, wpisy.
5. Organizowanie wydań: kanaryjski/niebiesko-zielony, schemat pierwszej migracji.
6. Uruchom katalog wersji/zdarzeń/kluczy i odreaguj procesy.
7. Przeprowadzić chaos/perf/testy bezpieczeństwa, zorganizować playbooks.
8. Regularnie zmieniaj minimalizację danych i zgodność z przepisami.

17) Słownik

Contract-first - projekt API poprzez formalne umowy do kodu.
Idempotence-Key - klucz, który sprawia, że operacja powtarza się bezpiecznie.
AsyncAPI - specyfikacja interfejsów zdarzeń.
QoS - Jakość usługi/Klasa priorytetowa.
DLQ - „martwa kolejka” dla wiadomości problemowych.
Błąd w budżecie - wskaźnik „spalania” budżetu błędu w stosunku do SLO.

Podsumowanie: API ekosystemu nie jest zbiorem punktów końcowych, lecz zarządzanym systemem umów, bezpieczeństwa, kwot i obserwowalności. Stosując się do tych ram, ekosystem zyskuje szybkie integracje, przewidywalne SLO i bezpieczną ewolucję bez przestojów - od warstwy sieciowej i uwierzytelniania do przepływów zdarzeń i raportowania.