Ενιαίο API για τους παρόχους: σχεδιασμός, έκδοση, συμβατότητα

Πλήρες άρθρο

💡 18+. Τεχνικό υλικό για ομάδες ένταξης και πλατφόρμας. Δεν είναι μια κλήση για να παίξει.

1) Γιατί «single API» και τι είναι

Ένα ενιαίο API είναι μια προδιαγραφή και ένα σύνολο τελικών σημείων/εκδηλώσεων μέσω των οποίων κάθε πάροχος περιεχομένου (RGS, ζωντανό στούντιο, τζάκποτ, KYC/AML, θυγατρικές) επικοινωνεί με την πλατφόρμα σύμφωνα με τους ίδιους κανόνες:

ενιαίο μοντέλο πόρων (παίκτες, συνεδρίες, στοιχήματα, διακανονισμοί, μπόνους, τζάκποτ, πληρωμές), κοινές συμβάσεις εκδηλώσεων και αναγνωριστικά, πρότυπα ασφάλειας και οπισθοδρομικής συμβατότητας, SDK/εργαλεία για την επιτάχυνση της ολοκλήρωσης.

Στόχος: μείωση του χρόνου ολοκλήρωσης, μείωση των σφαλμάτων στις «χρηματικές διαδρομές» και παροχή προβλέψιμων αναβαθμίσεων.

2) Αρχές σχεδιασμού

1. Πρώτος τομέας. Πρώτον, το λεξικό και οι αναλλοίωτες (ρυθμός, ρύθμιση, όρια RG), στη συνέχεια τελικά σημεία.

2. Συμβατότητα εξ ορισμού. Οποιαδήποτε αλλαγή είναι συμβατή εξ ορισμού. ρήξη των αλλαγών αυστηρά με τη διαδικασία.

3. Idempotency παντού. Όλες οι εντολές χρημάτων είναι επαναλαμβανόμενες χωρίς παρενέργειες.

4. Τα γεγονότα είναι πηγή αλήθειας. πτητικές λειτουργίες → εκδηλώσεις στο λεωφορείο· Η ανάλυση ακούει το λεωφορείο, όχι το OLTP.

5. Ελάχιστο προνόμιο και μηδενική εμπιστοσύνη. Μάρκες, υπογραφές, κατάτμηση ανά εμπορικό σήμα/περιφέρεια.

6. Παρατηρησιμότητα. Tend-to-end 'trace _ id', κατανοητό μοντέλο σφάλματος, p95/p99 μετρήσεις.

3) Μοντέλο πόρων (απλουστευμένο)

Παίκτης: πλαϊνός παίκτης πλατφόρμας ψευδο-ID, geo/νόμισμα/καταστάσεις RG.

Συνεδρία: δίαυλος μεταξύ του παρόχου και της πλατφόρμας ('session _ id', TTL, geo/περιορισμοί).

Στοίχημα: έγκριση/χρέωση στοιχήματος.

Διακανονισμός: Στρογγυλή έκβαση και κέρδη.

Bonus/Wager: Κατάσταση ισοζυγίου Bonus/Vager.

Τζάκποτ: συνεισφορές/ενεργοποιήσεις/πληρωμές.

Γεγονός: αμετάβλητα domain events (Kafka/ανάλογα).

Αναγνωριστικά: 'tenant _ id', 'brand _ i ,' region ',' player _ id ',' session _ id ',' round _ id ',' bet _ id ',' settlement _ id '. Όλες οι συμβολοσειρές, παγκοσμίως μοναδικές (UUID/KSUID/Snowflake), περιλαμβάνονται σε κούτσουρα και εκδηλώσεις.

4) Συμβάσεις API: αιτήματα, απαντήσεις, σφάλματα

4. 1 Εξουσιοδότηση και ασφάλεια

Client Credentials ή mTLS + Request Body Signature (HMAC/EdDSA).

: 'στοιχήματα: γράψτε', 'οικισμοί: γράψτε', 'συνεδρίες: διάβασε', 'γεγονότα: δημοσίευση'.

Σε κάθε αίτηση απαιτούνται κεφαλίδες:

«X-Trace-I ,» X-Brand-I , «X-Region», «X-Idempotency-Key».

4. 2 Παραδείγματα τελικών σημείων

Δημιουργία συνεδρίας


POST/v1/συνεδριάσεις
{
« » « » νόμισμα «:» EUR «,» locale «:» de-DE «,» περιορισμοί «: {» max _ bet «: 5,» rg _ flag : [«self _ exclusion»: false]}
}
→ 201
{
«session_id":"s_456,» «expires_at":"2025-10-23T19:10:00Z»
}

Έγκριση επιτοκίου (κύτος)


POST/v1/στοιχήματα/εξουσιοδότηση
Κεφαλίδες: X-Idempotency-Key: bet_r_8c12_1
{
"session_id":"s_456," "bet_id":"b_001," round_id":"r_8c12, "" ποσό ": {" ποσό ": 2. 00, «νόμισμα»:» EUR»}
}
200 {"status": "εξουσιοδοτημένος", "hold _ i →:" h _ zz1 "}

Διακανονισμός


POST/v1/στοιχήματα/διακανονισμός
Κεφαλίδες: X-Idempotency-Key: settle_r_8c12_1
{
"bet_id":"b_001," "round_id":"r_8c12," win ": {" ποσό ": 14. 60, "νόμισμα":" EUR"}, "bonus_state":{"in_bonus":true,"freespins_left":7}
}
200 {"status": "credited", "settlement _ i →:" st _ 77 "}

4. 3 Σφάλματα (ενιαίο μοντέλο)

'κωδικός': машинное имя ('RG _ BLOCK', 'LIMIT _ OVERED', 'DUPLICATE', 'IDEMPOTENCY _ MISMATCH', 'INVALID _ STATE', 'AUTH _ FAILSTLAILL L L L.

'message': ενημέρωση για το άτομο.

'retryable': 'true/false'.

'trace _ i : αναζήτηση των αρχείων καταγραφής.

Παράδειγμα:


409 ΣΥΓΚΡΟΎΣΕΙΣ
{
«κωδικός «: «DUPLICATE», «μήνυμα»:» Στοίχημα που έχει ήδη εγκριθεί με διαφορετικό ποσό», «retryable»: ψευδές, «trace_id":"tr_a1b2c3»
}

5) Λεωφορείο και κυκλώματα εκδηλώσεων

5. 1 Βασικά θέματα

'player. που καταχωρίσθηκε ως «», συνεδρίαση. Έναρξη λειτουργίας	τέλος "
"bet. εγκεκριμένη	διακανονισμός
"bonus. εκδοθέν	καταναλωθείσα
"wager. την πρόοδο. επικαιροποίηση "
"jackpot. συνεισφορά	ενεργοποιείται
'rg. όριο. χτύπημα ',' rg. reality_check'
"wallet. χρεωστική. ',' πορτοφόλι. πίστωση ".

5. Σύστημα γεγονότων 2 (Avro/JSON Schema)

json
{
"event_id":"uuid," "event_type":"bet. settled «,» occurred_at":"2025-10-23T16:21:05Z, «» tenant_id":"brand-7, «» region «:» EU «,» player_id":"p_19f3, «trace_id":"tr_a1b2c3,» «payload»: {
«round_id":"r_8c12,» «στοίχημα «: {«ποσό»: 1. 00, «νόμισμα»:» EUR»}, «win «: {«ποσό»: 14. 60, "νόμισμα":" EUR"}, "in_bonus":true
}, "idempotency_key":"bet_r_8c12_1," "schema_version":"1. 2. 0"
}

Κανόνες: προς τα πίσω συμβατή εξέλιξη των συστημάτων, μητρώο + δοκιμές συμβάσεων.

6) Έκδοση API: στρατηγικές και κανόνες

6. 1 Πού να αποθηκεύσετε την έκδοση

Έκδοση διαδρομής: '/v1/... "(μόνο κρύπτη/διαδρομή).

Έκδοση κεφαλίδας: 'Αποδοχή: εφαρμογή/vnd. πλατφόρμα. api + json· έκδοση = 1. 2`.

Γεγονότα: 'schema _ version' στο πεδίο γεγονότων + μητρώο.

Πρακτική: διαδρομή για HTTP, schema_version για εκδηλώσεις, σημαίες για δυνατότητες σημείων.

6. 2 SemVer και τύποι μεταβολών

PATCH (ήσσονος σημασίας) - αντίστροφη σύνδεση: νέα προαιρετικά πεδία, νέα τελικά σημεία, νέοι τύποι συμβάντων.

MAJOR - σπάσιμο: μετονομασία πεδίων, αλλαγή σημασιολογίας, διαγραφή. Επιτρέπεται μόνο μέσω του νέου «/vN/» και της εξάντλησης του παλαιού.

6. 3 Συμβάσεις σταθερότητας (οι οποίες δεν μπορούν να παραβιαστούν)

Ονόματα και τύποι βασικών πεδίων αναγνώρισης ('_ i ,' idempotency _ key ').

Νομισματικό μοντέλο («ποσό/νόμισμα», ακρίβεια).

Σημασιολογία κατάστασης ('εξουσιοδοτημένη', 'πιστωμένη', 'χαμένη' κ.λπ.).

Ιδιαιτερότητα: η συμπεριφορά επανάληψης ορίζεται αυστηρά.

7) Συμβατότητα και εξέλιξη

7. 1 Προσθήκη (ασφαλής)

Νέα προαιρετικά πεδία με αθετήσεις.

Νέα συμβάντα/τελικά σημεία χωρίς αλλαγή υφιστάμενων.

Επέκταση Enum με επιστροφή στο «άγνωστο».

7. 2 Μεταβολές (επικίνδυνες)

Αλλαγή τύπου πεδίου (αριθμός γραμμής).

απαιτείται προαιρετική →.

Αντιστροφή της επιχειρηματικής λογικής («διακανονισμός» πριν από την «έγκριση»).

χρειάζονται ένα νέο σημαντικό οδηγό έκδοσης και μετανάστευσης.

7. Αποσύνθεση

Το πεδίο/τελικό σημείο σημειώνεται με 'deprecated _ since: 1. 7 ',' αφαιρέθηκε _ σε: 2. 0`.

Ανακοίνωση: δημοσιευμένες σημειώσεις, ενημερωτικό δελτίο, κεφαλίδες υποτίμησης ('Sunset', 'Deprecation').

Εντοπισμός της χρήσης «παρωχημένων» διαδρομών για προληπτικές κοινοποιήσεις εταίρων.

8) Ιδιαιτερότητα και συνέπεια

Η κεφαλίδα «X-Idempotency-Key» απαιτείται για όλες τις λειτουργίες καταγραφής.

Σημασιολογία: επαναλάβετε με το ίδιο κλειδί → το ίδιο αποτέλεσμα (200 με το ίδιο σώμα).

Τα κλειδιά συνδέονται με μια σύνθεση παραμέτρων (για παράδειγμα, 'στοίχημα _ id + ποσό').

Sagas για μακριές διαδικασίες: «εξουσιοδοτήστε → δεσμεύσετε/κλειδώστε → διακανονίσετε → πίστωση», αποζημίωση - «rollback» γεγονότα.

9) Σελιδοποίηση, φίλτρα, διαλογή

Σελιδοποίηση με βάση τον δρομέα (αυστηρά προτιμώμενη «σελίδα/όριο» για μεγάλα νήματα).

Ενοποίηση: '? δρομέας =... & όριο = 200 & τάξη = asc '.

Στην απάντηση: 'next _ cursor', 'has _ more'.

Φίλτρα: με το χρόνο ('συνέβη _ στο _ από/σε'), 'ενοικιαστής _ id', 'παιχνίδι _ id', 'status'.

10) Τόποι, νομίσματα, κατοικία δεδομένων

νόμισμα σε ISO-4217, η ακρίβεια αποθηκεύεται στο σύστημα («κλίμακα»), υπολογισμούς - σε μονάδες ελάσσονος σημασίας (λεπτά).

Locali - BCP 47 («en-GB», «pt-BR»).

Σε κάθε αίτημα - «περιφέρεια», Οι συναλλαγές PII και μετρητών δεν διασχίζουν περιφέρειες.

PII και RLS που κρύβονται σε BI showcases.

11) Παρατηρησιμότητα και όρια

Απαιτούμενες επικεφαλίδες: "X-Trace-I ," X-Provider-Id ", συσχέτιση με γεγονότα.

Μετρήσεις: p50/p95/p99 καθυστέρηση, ρυθμός σφάλματος (ανά κωδικό), διακίνηση, καθυστέρηση αναμονής (για γεγονότα).

Όρια επιτοκίου: ανά πάροχο/ανά εμπορικό σήμα· απαντήσεις από το «Retry-After».

Έλεγχος WORM των κρίσιμων αλλαγών (όρια, ομάδες RTP, τύποι τζάκποτ).

12) Έλεγχος και ποιότητα των συμβάσεων

Δοκιμές συμβάσεων (σύμφωνο/άλλα): πάροχος ↔ πλατφόρμα ↔ καταναλωτές εκδηλώσεων.

Φορτίο: «καταιγίδα» τιμών/οικισμών. στόχοι του p95.

Περιπτώσεις χάους: διπλή παράδοση, εκτός παραγγελίας, καθυστερήσεις πορτοφολιών.

Sandbox '/sandbox 'με φανταστικά χρήματα και δοκιμή' player _ id '.

13) SDK, γεννήτριες και τεκμηρίωση

Γενιά OpenAPI/AsyncAPI → SDK (TypeScript/Java/Kotlin/Go/Rust).

Παραδείγματα κωδικών για 'authorize/settle/rollback', retrays, και χειρισμό σφαλμάτων.

Ζωντανή δεξαμενή με παραδείγματα αιτήματος/απόκρισης (curl + JSON), συλλογή Postman/Αϋπνία.

Changelog με τύπους αλλαγής και ετικέτες συμβατότητας.

14) Χάρτης πορείας για τη μετανάστευση (παράδειγμα)

1. v1. 6 → v1. 7 (ήσσονος σημασίας) Προστέθηκε το πεδίο «bonus _ state» στο πεδίο «settle» (προαιρετικά).

2. v1. x ανακοίνωση EOL: για 6 μήνες - κεφαλίδα + κεφαλίδα «Απερήμωσης» + ταμπλό χρήσης.

3. v2. 0 (μείζων): ατομικό 'wallet. δεσμεύεται '(πρώην σιωπηρό), απαιτείται νέο πεδίο' settlement _ id '.

4. Οδηγός μετάβασης: χαρτογράφηση πεδίου, χρονοδιάγραμμα, fichflag της «διπλής γραφής» (παράλληλη δημοσίευση των γεγονότων 'v1 '/' v2').

5. Ηλιοβασίλεμα v1: παρεμπόδιση νέων ολοκληρώσεων, με επέκταση μόνο για εξαιρέσεις SLA.

15) Κατάλογοι ελέγχου

Για αρχιτέκτονες πλατφορμών

Υπάρχει ένα ενιαίο λεξικό οντοτήτων τομέα και αναλλοίωτων.
Μητρώο OpenAPI/AsyncAPI + Schema, semver, διαδικασία αποσβέσεων.
Ταυτότητα σε όλες τις πράξεις εγγραφής. Τα κλειδιά είναι τεκμηριωμένα.
Ενιαίο μοντέλο και κωδικοί σφάλματος.
Sagas and outbox/CDC on Money Ways.
Όρια επιτοκίων, παρατηρησιμότητα, έλεγχος WORM.
Οι δοκιμές Sandbox και συμβάσεων είναι διαθέσιμες στους εταίρους.
Κατοικία δεδομένων και RLS/κάλυψη.

Για τον πάροχο

Πάντα στέλνω το «X-Trace-Id» και το «X-Idempotency-Key».

Επεξεργάζομαι ζητώ επαναλήψεις με ασφάλεια. Δεν δημιουργώ διπλά.
Επεξεργασία 'Απερήμωση/Ηλιοβασίλεμα' και ανάγνωση Changelog.
Δημοσιεύω/διαβάζω εκδηλώσεις σύμφωνα με τα συστήματα μητρώων. Κρατάω μια εκδοχή.
Έχω επαναπροσδιορισμό/οπισθοδρόμηση και απεμπλοκή στο πλευρό μου.

16) Αντι-μοτίβα (κόκκινες σημαίες)

Χειροκίνητες επεξεργασίες υπολοίπων/διακανονισμών στη βάση δεδομένων.

Εκδοτικές εκδηλώσεις «προηγούμενες» outbox/CDC.

Καμία ταυτότητα → διπλή πληρωμή/χρέωση.

Ανάμειξη PII/χρημάτων διαφορετικών περιφερειών χωρίς σήμανση «περιφέρεια».

Το «ήσυχο» σπάσιμο αλλάζει χωρίς νέα έκδοση και μείωση.

Δημιουργία SDK χειροκίνητα (μετατόπιση με πραγματικές προδιαγραφές).

Μεταναστεύσεις μεγάλης έκρηξης χωρίς σημαίες και διπλή γραφή γεγονότων.

Μια ενιαία API δεν είναι μόνο μια «συλλογή τελικών σημείων», αλλά μια σύμβαση οικοσυστήματος: ένα συνεπές λεξικό, σταθερές νομισματικές αναλλοίωτες, επαληθευμένα γεγονότα, σαφείς κανόνες συμβατότητας και διαχειρίσιμες μειώσεις. Βασιζόμενη στη σημασιολογική έκδοση, την ταυτότητα, το outbox/CDC, την παρατηρησιμότητα και την ισχυρή ασφάλεια, η πλατφόρμα συνδέει τους παρόχους γρήγορα και ανώδυνα, και οι αναβαθμίσεις μετατρέπονται από κίνδυνο σε ρουτίνα.