Operacje API

(Sekcja: Operacje i zarządzanie)

1) Cel i zasady

API to „warstwa operacyjna” ekosystemu: wszystko, co nie jest zautomatyzowane za pomocą umowy, zmienia się w ręczną pracę i ryzyko.

• Kontrakt pierwszy: pierwsza specyfikacja (OpenAPI/JSON Schema/AsyncAPI), a następnie wdrożenie.
• Bezpieczne domyślnie: minimalne zakresy, krótki TTL, wzajemne TLS/podpisy.
• Obserwowalne: śledzenie od końca do końca i mierniki SLA.
• Idempotent: Powtórz bezpiecznie.
• Kompatybilność wsteczna: ewolucja bez „łamania” zmian.
• Podlega audytowi: potwierdzone kryptograficznie fakty (wpływy).

2) Umowa i modele (odniesienie)

OpenAPI dla żądań synchronizacji; AsyncAPI dla wydarzeń/haków internetowych.
Wymagane pola w każdym zasobie to 'id',' wersja ',' created _ at ',' updated _ at ',' lokator ',' region ',' trace _ id'.

Przykład fragmentu umowy

yaml paths:
/payments/payouts:
post:
operationId: createPayout requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutRequest'
responses:
"202": { $ref: '#/components/responses/AcceptedWithReceipt' }
headers:
Idempotency-Key:
schema: { type: string }
required: true components:
responses:
AcceptedWithReceipt:
description: Accepted, processing asynchronously headers:
Receipt-Hash: { schema: { type: string } }

3) Uwierzytelnianie, autoryzacja, zakresy

OAuth2/OIDC dla użytkowników/partnerów client-credentials/JWT дла S2S.
Scopes/resource roles: 'payments. napisz ',' katalog. czytaj „,” audyt. wywóz ".
ReBAC: dostęp „własnością” (najemca/konto/subkont).
Tajemnice JIT: krótkotrwałe żetony, oprawa urządzenia/podsieci/regionu.
Postawa urządzenia i mTLS dla operacji krytycznych (płatności, klucze).

4) Idempotencja i „dokładnie raz”

Idempotence-Key (nagłówek) + dedup by '(klucz, konto, trasa)' w oknie TTL.
Outbox/CDC to post events - gwarantowana dostawa.
Dokładnie jednorazowe skutki: skutki uboczne są rejestrowane przez dziennik transakcji; powtórzenie prowadzi do tego samego „potwierdzenia” ('receipt _ hash').
Zasady retry: wykładnicze cofnięcie, jitter, maksymalne okna.

5) Limity, kwoty, priorytety

Limity stawek: na klucz/najemca/trasa/region; „miękkie” (429) i „twarde” (cutoff).
Kwoty/budżety: miesięczne/dzienne czapki, haki internetowe „ CapReached”.
Fair-use: priorytet najemców według poziomu usług (Gold/Silver/Bronze).
Wybuchy: krótkie wybuchy bez degradacji sąsiadów.

6) Paginacja, filtry, próbki

Na bazie kursora (stabilne zamówienie - „created _ at, id”), „page _ size” ≤ 1000.
Próbki w kroju czasowym („od”, „do”, „znak wodny”) dla dzienników/transakcji.
Filtering DSL: whitelisted бола, '? status =... & tenud =... & region =...'.
Wskazówki dotyczące spójności: 'snapshot _ at '/' as _ of' do zgłaszania API.

7) Weryfikacja i kompatybilność

SemVer: 'v1', 'v1. 1 "(rozszerzenia)," v2 "- tylko na nowych ścieżkach/obszarach nazw.
Zasady ewolucji: dodaj tylko pola/wartości, „deprecate → remove” przez okno.
Testy zgodności: „umowy-as-tests” (napędzane przez konsumentów).

8) Wydarzenia, haki i pokwitowania

AsyncAPI opisuje tematy/ładunek użytkowy/podpisy.

Podpis: HMAC/EdDSA, nagłówki „X-Signature”, „X-Nonce”, „X-Timestamp” (wąskie okno)

Paragony: 'receipt _ hash' i podpis DSSE na zdarzeniach krytycznych (płatności, zmiany RTP/limit, cenniki).
Retrai i dedup: idempotencja według 'idempotence _ key '/' event _ id'.
DLQ/kwarantanna: nieprawidłowe/powtarzające się raporty z przyczynami.

9) Obserwowalność i jakość

Ślady: obowiązkowe 'trace _ id/span _ id' poprzez gateway/business events/webhooks.
Metryki: dostępność, p50/p95/p99, błąd, wsteczny, koszt za 1k.
Kłody: ustrukturyzowane, bez tajemnic/PII; "najemca/region/wersja 'abel.
SLO/alerty: warunki zorientowane na SLO i auto-runy (pauza/ponowna trasa/rolka).

10) Błędy i semantyka statusu

2xx - sukces (202 dla operacji asynchronicznych).
4xx - błąd klienta (422 - walidacja, 409 - konflikt/idempotencja, 429 - granice).
5xx - tymczasowe problemy.
Ciało błędu: 'code', 'message', 'trace _ id',' hint ',' retry _ after? '.
UX dla partnerów: tabela „co robić” dla każdego błędu.

11) Kod polityki (OPA/ABAC)

Scentralizowana autoryzacja: „who/what/where/when/why”.
Zasady w Git, przegląd kodu, testy CI (przed lotem: "czy polityka pozwoli? »).
Sprawdź SoD: „utwórz płatność” „zatwierdzaj”.

12) Bezpieczeństwo, prywatność, zgodność

Minimalizacja PII: tokenizacja/maski, dostęp do podstawowej tylko poprzez zatwierdzone jabs.
Sekrety: Skarbiec/KMS, krótki TTL, obroty; zakaz wspólnych tajemnic.
Szyfrowanie: mTLS/TLS 1. 3, AES-GCM w stanie spoczynku, HSTS/PKP w stosownych przypadkach.
Świadomość jurysdykcji - Lokalizacja danych/kluczy w poszczególnych regionach.
Dzienniki audytu: WORM, plastry Merkle, podpisy DSSE.

13) Działanie: SLI/SLO i deski rozdzielcze

• Dostępność na trasę/region.
• p95 opóźnienie (czytać/pisać).
• Sukces haków (paragonów), opóźnienie dostawy.
• Szybkość błędów/powtarzalność.
• Koszt za 1k żądania i wyjście.

SLO (przykład): 99. 95% dostępności; p95 ≤ 120/250 ms; webhaki ≥ 99. 5 %/5-min; P1 MTTR ≤ 60 min.

14) Zarządzanie zmianami (wydania/rolki)

Blue-Green/Canary dla bram i tras krytycznych.
Ficheflags za zachowanie bez zwolnienia.
Rozwiń → Migrate → Kontrakt na schematy i ładunek.
Руна: Rollback Release, Disable Flag, Re-route, Flush Cache.
Artefakty: podpisane obrazy/manifesty, rejestr wersji.

15) SDK, klienci, piaskownice

Oficjalne SDK (TS/Java/Python/Go) z tym samym błędem i semantyką retrasy.
Środowiska piaskownicy z klawiszami testowymi/certyfikatami i symulatorami PSP/KYC/content provider.
Testy kontraktowe są zawarte w CI SDK, kompatybilność nocna.

16) Model danych (uproszczony)

'api _ key' '{id, lokator, scopes [], ttl, created_by}'

„rate _ plan” „{najemca, kwoty {route → cap}, pęknięcie, priorytet}”

'quest _ log' '{trace _ id, trasa, aktor, idempotency_key?, status, latency_ms, region, cost_unit}'

„webhook _ receipt” „{event _ id, punkt końcowy, status, próby, receipt_hash, podpis}”

„policy” „{wersja, zasady, sygnatariusz, dsse}”

17) RACI

18) Wskaźniki jakości

Drift kontraktu: 0 „łamanie” zmiany bez deprecate.
Wskaźnik błędu idempotencji: ≤ 0. 01%.
Sukces Webhook: ≥ 99. 5%, lag p95 ≤ 60 s.
Auth Fail vs Nadużycie: udział złośliwych bloków, hałas ≤ poziom docelowy.
Cost/1k: kontrola według tras i regionów (budżety/wpis).
Przyjęcie SDK: udział ruchu poprzez oficjalne SDK.

19) Playbooks incydentów

Spike 429/limits: podnieść czapkę na złoto, rozdrabniając „hałaśliwe” klucze, połączenie z partnerem.
WebhookLag: zwiększenie pracowników/partii, priorytetowe kolejki, tymczasowo wyłączyć opcjonalne haki internetowe.
• Niedopasowanie (katalog/FX/Tax): pojednanie wersji, niepełnosprawność siły pamięci podręcznej, artefakt rollback, odszkodowanie.
Przerwa PSP: przełączanie trasy, kwarantanna transakcji „szarych”, powtórka.
Kompromisowy klucz API: natychmiastowe wycofanie, rotacja, audyt ostatnich 30 dni.

20) Specyfika iGaming/fintech

RTP/Limits API: tylko agregaty i wersje profilowe; zmiany - z paragonami.
Płatności/wypłaty: 202 + podpisane haki internetowe; zamówić klucz idempotencji.
Podmioty powiązane: dedup konwersji, escrow do sporów, podpisane raporty.
Responsible play: Expose „guardrails API” dla limitów i zdarzeń RG.

21) Lista kontrolna wdrażania

• Opisana umowa (OpenAPI/AsyncAPI), walidacja CI i testy konsumenckie.
• Skonfigurowane OAuth2/OIDC, zakresy, tajemnice JIT i mTLS dla tras krytycznych.
• Wprowadzono idempotencję, retrai, DLQ i kwarantannę.
• Pułapy/kwoty/priorytety i wpisy.
• Paginacja kursora, spójne próbki „as _ of”.
• Polityka weryfikacyjna i deprecacyjna.
• Haki internetowe z podpisami/paragonami, powtórką i dedup.
• Trace/metrics/logs, SLO i runs.
• Dzienniki WORM, podpisy DSSE, plastry Merkle.
• SDK, piaskownica, symulatory, próbki kodowe i jak.

22) FAQ

Dlaczego 202 dla długich operacji?
Aby nie utrzymywać połączenia i zapewnić niezawodny przekaz/paragon za pośrednictwem haka internetowego.

Czy potrzebujesz zarówno OpenAPI i AsyncAPI?
Tak: synchronizacja dla poleceń/żądań, async dla wydarzeń/negocjacji państwowych.

Jak uniknąć złamania zmian?
Dodaj tylko regułę, deprecate → obserwuj → usuń, kontrakt z testem klienta.

Gdzie przechowywać pokwitowania?
W strefie WORM z podpisami; 'receipt _ hash' jest zwracany klientowi i sprawdzany na żądanie.

Podsumowanie: Operacje za pośrednictwem API to dyscyplina kontraktu i działania: model ścisłego dostępu i idupotencja, limity i wersje, obserwowalność i SLO, podpisy i paragony. Dodaj piaskownice i SDK - a partnerzy będą integrować się szybko, bezpiecznie i przewidywalnie, a przedsiębiorstwa będą skalować bez utraty jakości lub zgodności.