Pojedynczy API dla dostawców: projekt, wersja, kompatybilność

Pełny artykuł

💡 18+. Materiały techniczne dla zespołów integracyjnych i platformowych. Ani telefonu do zabawy.

1) Dlaczego „pojedynczy API” i co to jest

Pojedynczy API to specyfikacja i zestaw punktów końcowych/zdarzeń, za pośrednictwem których każdy dostawca treści (RGS, live studio, jackpot, KYC/AML, affiliates) komunikuje się z platformą zgodnie z tymi samymi zasadami:

ujednolicony model zasobów (gracze, sesje, zakłady, rozliczenia, premie, jackpoty, płatności), wspólne umowy i identyfikatory zdarzeń, standardy bezpieczeństwa i kompatybilności wstecznej, SDK/narzędzia do przyspieszenia integracji.

Cel: skrócenie czasu na integrację, zmniejszenie błędów na „ścieżkach pieniężnych” i zapewnienie przewidywalnych ulepszeń.

2) Zasady projektowania

1. Domena pierwsza. Najpierw słownik i niezmienne (szybkość, ustawienie, limity RG), a następnie punkty końcowe.

2. Domyślnie kompatybilność. Każda zmiana jest domyślnie kompatybilna; łamanie zmian ściśle przez proces.

3. Wszędzie idempotencja. Wszystkie polecenia pieniężne są powtarzalne bez skutków ubocznych.

4. Wydarzenia są źródłem prawdy. Operacje → wydarzenia do autobusu; Analityka słucha autobusu, nie bije OLTP.

5. Najmniejszy przywilej i zero zaufania. Żetony, podpisy, segmentacja według marki/regionu.

6. Obserwowalność. End-to-end 'trace _ id', zrozumiały model błędu, metryki p95/p99.

3) Model zasobów (uproszczony)

Gracz: Platform side player pseudo-ID, geo/waluta/RG statusy.

Sesja: kanał między dostawcą a platformą ('session _ id', TTL, geo/ograniczenia).

Zakład: autoryzacja/debetowa zakładu.

Rozrachunek: okrągły wynik i wygraj kredyt.

Bonus/Wager: Bonus/vager status salda.

Jackpot: składki/wyzwalacze/wypłaty.

Zdarzenie: niezmienne zdarzenia domeny (Kafka/analogi).

Identyfikatory: 'lokator _ id',' brand _ id', 'region', 'player _ id',' session _ id', 'round _ id',' bet _ id', 'settlement _ id'. Wszystko - ciąg, globalnie unikalny (UUID/KSUID/Snowflake), są zawarte w dziennikach i wydarzeniach.

4) Umowy API: prośby, odpowiedzi, błędy

4. 1 Autoryzacja i bezpieczeństwo

OAuth2 poświadczenia klienta lub mTLS + żądanie podpisu organu (HMAC/EdDSA).

Сковида: 'bets: write', 'settlements: write', 'sessions: read', 'events: publish'.

Nagłówki są wymagane w każdym żądaniu:

'X-Trace-Id',' X-Brand-Id', 'X-Region', 'X-Idempotence-Key'.

4. 2 Przykłady punktów końcowych

Tworzenie sesji


POST/v1/sesje
{
"player_id":"p_19f3," "game_id":"studio:slot_forge_02," "waluta": "EUR", "locale": "de-DE", "ograniczenia": {"max _ bet": 5, "rg _ flags': [" self _ exclusion ": false]}
}
→ 201
{
„session_id":"s_456,” „expires_at":"2025-10-23T19:10:00Z”
}

Autoryzacja stawki (blokada)


POST/v1/zakłady/autoryzacja
Nagłówki: X-Idempotency-Key: bet_r_8c12_1
{
„session_id":"s_456,” „bet_id":"b_001,” „round_id":"r_8c12,” „kwota „: {” kwota”: 2. 00, „waluta”:” EUR”}
}
→ 200 {"status": "autoryzowany", "hold _ id':" h _ zz1 "}

Rozrachunek


POST/v1/zakłady/rozrachunek
Nagłówki: X-Idempotency-Key: settle_r_8c12_1
{
"bet_id":"b_001," "round_id":"r_8c12," "wygraj': {" kwota ": 14. 60, "waluta":" EUR"}, "bonus_state":{"in_bonus":true,"freespins_left":7}
}
→ 200 {"status": "credited", "settlement _ id':" st _ 77 "}

4. 3 Błędy (pojedynczy model)

„code”: мабиновима („RG _ BLOCK”, „LIMIT _ EXCEEDED”, „DUPLICATE”, „IDEMPOTENCY _ MISMATCH”, „INVALID _ STATE”, „AUTH _ FAILED”)

„message”: krótki dla danej osoby.

„zwrotne”: „prawdziwe/fałszywe”.

'trace _ id': wyszukiwanie dzienników.

Przykład:


409 KONFLIKT
{
„kod „: „DUPLICATE”, „message”:” Bet już autoryzowany z inną kwotą”, „retryptable”: false, „trace_id":"tr_a1b2c3”
}

5) Autobus imprezowy i obwody

5. 1 Podstawowe tematy

"player. sesja zarejestrowana „,”. rozpoczęty	zakończone "
'bet. autoryzowany	rozliczone
'bonus. wydane	spożywane
"wager. postęp. zaktualizowany "
'jackpot. wkład	uruchomiony
'rg. limit. trafienie ',' rg. reality_check'
'portfel. debit „.,” portfel. kredytu ".

5. 2 Schemat zdarzeń (Avro/JSON Schema)

json
{
"event_id":"uuid," "event_type":"bet. rozliczane", "occurred_at":"2025-10-23T16:21:05Z," "tenant_id":"brand-7," "region":" UE", "player_id":"p_19f3," "trace_id":"tr_a1b2c3," "ładunek użytkowy": {
„round_id":"r_8c12,” „zakład „: {„kwota”: 1. 00, „waluta”:” EUR”}, „win „: {„kwota”: 14. 60, "waluta":" EUR"} ", in_bonus":true
}, "idempotency_key":"bet_r_8c12_1," "schema_version":"1. 2. 0"
}

Zasady: wsteczna ewolucja systemów, rejestr + testy kontraktowe.

6) Wersja API: strategie i zasady

6. 1 Gdzie przechowywać wersję

Wersja ścieżki: '/v1/... "(tylko cache/trasa).

Wersja nagłówka: 'Akceptuj: aplikacja/vnd. platforma. api + json; wersja = 1. 2`.

Zdarzenia: 'schema _ version' w polu zdarzeń + rejestr.

Praktyka: ścieżka dla HTTP, schema_version dla zdarzeń, flagi funkcji dla możliwości punktowych.

6. 2 SemVer i rodzaje zmian

PATCH (minor) - dokowanie wsteczne: nowe pola opcjonalne, nowe punkty końcowe, nowe rodzaje zdarzeń.

MAJOR - łamanie: zmiana nazwy pól, zmiana semantyki, usunięcie. Dozwolone tylko przez nowe '/vN/' i wyczerpanie starego.

6. 3 Stabilne umowy (których nie można złamać)

Nazwy i typy pól identyfikacyjnych kluczy ('_ id',' idempotence _ key ').

Model pieniężny („kwota/waluta”, dokładność).

Semantyka statusu („autoryzowana”, „uznana”, „utracona” itp.).

Idempotencja: zachowanie powtarzania jest ściśle zdefiniowane.

7) Zgodność i ewolucja

7. 1 Dodaj (bezpiecznie)

Nowe pola opcjonalne z domyślnymi.

Nowe wydarzenia/punkty końcowe bez zmiany istniejących.

Przedłużenie enum z zapadnięciem w „nieznanym”.

7. 2 Zmiany (ryzykowne)

Zmień typ pola (numer → linia).

opcjonalne → wymagane.

Odwrócenie logiki biznesowej ('settle' przed 'authorize').

→ potrzebuje nowej głównej wersji i przewodnika migracji.

7. 3 Deprekcja

Pole/punkt końcowy jest oznaczony 'deprecated _ since: 1. 7 „,” usunięte _ w: 2. 0`.

Komunikat: uwagi do wydania, biuletyn informacyjny, nagłówki deprecacji („Zachód słońca”, „Deprecacja”).

Śledzenie wykorzystania „przestarzałych” ścieżek do proaktywnych powiadomień partnerskich.

8) Idempotencja i spójność

Nagłówek 'X-Idempotence-Key' jest wymagany do wszystkich operacji nagrywania.

Semantyka: powtarzać z tym samym kluczem → ten sam wynik (200 z tym samym ciałem).

Klucze są związane kompozycją parametrów (na przykład 'bet _ id + amount').

Sagi o długich procesach: „autoryzuj → commit/lock → settle → credit”; odszkodowanie - zdarzenia „rollback”.

9) Paginacja, filtry, sortowanie

Paginacja oparta na kursorze (ściśle preferowany 'page/limit' dla dużych wątków).

Zjednoczenie: '? cursor =... & limit = 200 & order = asc'.

W odpowiedzi: 'next _ cursor', 'has _ more'.

Filtry: według czasu ('occurred _ at _ from/to'), 'lokator _ id',' game _ id', 'status'.

10) Lokalizacje, waluty, rezydencja danych

Waluta w ISO-4217; dokładność jest przechowywana w schemacie („skala”), obliczenia - w małych jednostkach (centów).

Locali - BCP 47 („en-GB”, „pt-BR”).

W każdym wniosku - „region”; Transakcje PII i gotówkowe nie przekraczają regionów.

Maskowanie PII i RLS w pokazach BI.

11) Obserwowalność i ograniczenia

Wymagane pozycje: 'X-Trace-Id',' X-Provider-Id', korelacja z zdarzeniami.

Metryki: p50/p95/p99 opóźnienie, szybkość błędu (według kodów), przepustowość, kolejka opóźnienia (dla zdarzeń).

Limity stawek: na dostawcę/markę; odpowiedzi z 'Retry-After'.

Audyt WORM zmian krytycznych (limity, puli RTP, formuły jackpota).

12) Testowanie i jakość umów

Testy kontraktowe (Paktu/innych): dostawca, platforma i konsumenci imprez.

Obciążenie: „burza” stawek/rozliczeń; cele p95.

Przypadki chaosu: podwójna dostawa, brak zamówienia, opóźnienia portfela.

Piaskownica '/piaskownica 'z fikcyjnymi pieniędzmi i testem' player _ id'.

13) SDK, generatory i dokumentacja

OpenAPI/AsyncAPI → Generacja SDK (ΔScript/Java/Kotlin/Go/Rust).

Przykłady kodów dla 'authorize/settle/rollback', retras i obsługi błędów.

Dok na żywo z przykładami zapytania/odpowiedzi (curl + JSON), kolekcja Postman/Insomnia.

Changelog z rodzajami zmian i etykietami kompatybilności.

14) Plan działania w zakresie migracji (przykład)

1. v1. 6 → v1. 7 (minor) Dodano pole „bonus _ state” do „settle” (opcjonalnie).

2. v1. x Ogłoszenie EOL: przez 6 miesięcy - list + nagłówek „Deprecacja” + deska rozdzielcza użytkowania.

3. v2. 0 (główne): pojedynczy 'portfel. commit '(dawniej implicit), wymagane jest nowe pole' settlement _ id'.

4. Przewodnik migracji: mapowanie pól, linia czasu, fichflag „podwójnego pisania” (równoległa publikacja wydarzeń 'v1 '/' v2').

5. Sunset v1: blokowanie nowych integracji, rozszerzanie tylko o wyjątki SLA.

15) Listy kontrolne

Dla architektów platformy

Istnieje jeden słownik podmiotów domeny i niezmiennych.
OpenAPI/AsyncAPI + Schema Registry, semver, proces spadków.
Idempotencja we wszystkich operacjach pisania; klucze są udokumentowane.
Model i kody jednolitego błędu.
Sagi i outbox/CDC na sposoby pieniężne.
Limity stawek, obserwowalność, audyt WORM.
Piaskownica i testy kontraktowe są dostępne dla partnerów.
Rezydencja danych i RLS/maskowanie.

Dla dostawcy

Zawsze wysyłam 'X-Trace-Id' i' X-Idempotency-Key '.
Bezpiecznie przetwarzam żądania powtórzeń; Nie tworzę podwójnych.
Przetwarzanie „Deprecation/Sunset” i czytanie Changelog.
Publikuję/czytam wydarzenia zgodnie z systemami rejestrów; Trzymam wersję.
Mam retry/backoff i deduplication po mojej stronie.

16) Anty-wzory (czerwone flagi)

Ręczne edycje sald/rozliczeń w bazie danych.

Publikacja wydarzeń „past” outbox/CDC.

Brak idempotencji → duplikat płatności/debetów.

Mieszanie PII z pieniędzmi różnych regionów bez oznaczania „regionu”.

„Ciche” zmiany bez nowej wersji i spadku.

Generowanie SDK ręcznie (dryf z prawdziwymi specyfikacjami).

Migracje big-bang bez flag funkcji i podwójne pisanie wydarzeń.

Pojedynczy API jest nie tylko „zbiorem punktów końcowych”, ale kontraktem ekosystemowym: spójnym słownikiem, stabilnymi walutowymi niezmiennikami, zmienionymi zdarzeniami, jasnymi zasadami zgodności i możliwymi do opanowania obniżkami. Opierając się na wersji semantycznej, idempotencji, outbox/CDC, obserwowalności i silnym bezpieczeństwie, platforma łączy dostawców szybko i bezboleśnie, a aktualizacje zmieniają się z ryzyka do rutyny.