प्रदाताओं के लिए एकल एपीआई: डिजाइन, संस्करण, संगतता

पूरा लेख

1) "सिंगल एपीआई" क्यों और यह क्या है

एक एकल एपीआई एक विनिर्देश और समापन बिंदुओं/घटनाओं का एक सेट है जिसके माध्यम से कोई भी सामग्री प्रदाता (आरजीएस, लाइव स्टूडियो, जैकपॉट, केवाईसी/एएमएल, सहयोगी) समान नियमों के अनुसार मंच के साथ संचार करता है:

• एकीकृत संसाधन मॉडल (खिलाड़ी, सत्र, दांव, बस्तियां, बोनस, जैकपॉट, भुगतान), सामान्य घटना अनुबंध और पहचानकर्ता, सुरक्षा और पिछड़े संगतता मानक, एसडीके/उपकरण एकीकरण को गति देने के लिए।

लक्ष्य: समय-से-एकीकृत को कम करना, "धन पथ" पर त्रुटियों को कम करना और पूर्वानुमानित उन्नयन प्रदान करना।

---

2) डिजाइन सिद्धांत

1. डोमेन-पहला। सबसे पहले, शब्दकोश और आक्रमणकारी (दर, सेटिंग, आरजी सीमा), फिर समापन बिंदु।

2. डिफ़ॉल्ट रूप से संगतता। कोई भी परिवर्तन डिफ़ॉल्ट रूप से संगत है; प्रक्रिया द्वारा कड़ाई से परिवर्तन।

3. हर जगह पहचान। सभी धन आदेश दुष्प्रभावों के बिना दोहराए जा सकते हैं।

4. घटनाएँ सच्चाई का स्रोत हैं। संचालन - बस के लिए घटनाएं; एनालिटिक्स बस को सुनता है, ओएलटीपी को नहीं हराता है।

5. कम से कम विशेषाधिकार और शून्य-विश्वास। टोकन, हस्ताक्षर, ब्रांड/क्षेत्र द्वारा विभाजन।

6. अवलोकन। एंड-टू-एंड 'ट्रेस _ आईडी', समझ में आने वाली त्रुटि मॉडल, p95/p99 मेट्रिक्स।

---

3) संसाधन मॉडल (सरलीकृत)

खिलाड़ी: प्लेटफ़ॉर्म साइड प्लेयर छद्म-आईडी, भू/मुद्रा/आरजी स्टेटस।

सत्र: प्रदाता और मंच के बीच एक चैनल ('सत्र _ आईडी', टीटीएल, भू/प्रतिबंध)।

शर्त: शर्त प्राधिकरण/डेबिट।

निपटान: गोल परिणाम और क्रेडिट जीतना।

बोनस/दांव: बोनस/वेगर बैलेंस स्थिति।

जैकपॉट: योगदान/ट्रिगर/भुगतान।

घटना: अपरिवर्तित डोमेन घटनाएँ (काफ्का/एनालॉग्स)।

पहचानकर्ता: 'किरायेदार _ आईडी', 'ब्रांड _ आईडी', 'क्षेत्र', 'प्लेयर _ आईडी', 'सत्र _ आईडी', 'बीट _ आईडी', 'सेटलमेंट _ आईडी'। सभी - स्ट्रिंग, वैश्विक रूप से अद्वितीय (यूयूआईडी/केएसयूआईडी/स्नोफ्लेक), लॉग और घटनाओं में शामिल हैं।

---

4) एपीआई अनुबंध: अनुरोध, प्रतिक्रिया, त्रुटियां

4. 1 प्राधिकरण और सुरक्षा

OAuth2 क्लाइंट क्रेडेंशियल्स या mTLS + रिक्वेस्ट बॉडी सिग्नेचर (HMAC/EdDSA)।

Скоупы вида: 'दांव: लिखें', 'बस्तियाँ: लिखें', 'सत्र: पढ़ें', 'घटनाएँ: प्रकाशन'।

प्रत्येक अनुरोध में शीर्षिका की आवश्यकता होती है:

• 'एक्स-ट्रेस-आईडी', 'एक्स-ब्रांड-आईडी', 'एक्स-रीजन', 'एक्स-आइडेम्पोटेंसी-की'।

4. समापन बिंदुओं के 2 उदाहरण

सत्र निर्माण

POST/v1/सत्र
{
"" " " "मुद्रा":" ईयूआर", "लोकेल":" डी-डीई", "बाधाएं ": {"मैक्स _ बेट ": 5, "आरजी _ फ्लैग्स": [" सेल्फ _ एक्सक्लूज़न": गलत}]
}
→ 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 {"स्थिति ": "अधिकृत"," hold _ id":" h _ zz1"}

बस्ती

POST/v1/दांव/समझौता
हेडर: X-Idempotency-Key: settle_r_8c12_1
{
"bet_id":"b_001," "round_id":"r_8c12," "जीत ": {"राशि": 14। 60, "मुद्रा":" EUR"}, "bonus_state":{"in_bonus":true,"freespins_left":7}
}
→ 200 {"स्थिति ": "क्रेडिट ", "सेटलमेंट _ आईडी":" सेंट _ 77"}

4. 3 त्रुटियाँ (एकल मॉडल)

'कोड': ('RG _ BLOCK', 'LIMMINT _ EXCEEEDED', 'DUPLICATE', 'IDEMPOTENCY _ MISMATCH H H H H',')।

'मेसेज': व्यक्ति के लिए संक्षिप्त।

'retryable': 'true/fall'।

'ट्रेस _ आईडी': लॉग खोजने के लिए।

उदाहरण:

409 संघर्ष
{
"कोड": "DUPLICATE", "संदेश": "बेट पहले से ही एक अलग राशि के साथ अधिकृत है", "पुनर्विचार योग्य": गलत "," trace_id":"tr_a1b2c3 "
}

---

5) इवेंट बस और सर्किट

5. 1 बुनियादी विषय

5. 2 इवेंट स्कीमा (एवरो/JSON स्कीमा)

json
{
"event_id":"uuid," "event_type":"bet। बस गए," "occurred_at":"2025-10-23T16:21:05Z," "tenant_id":"brand-7," "क्षेत्र":" यूरोपीय संघ", "player_id":"p_19f3," "trace_id":"tr_a1b2c3," "पेलोड": {
"" "शर्त ": {"राशि": 1। 00, "मुद्रा":" EUR"}, "जीत ": {"राशि": 14। 60, "मुद्रा":" EUR"} ", in_bonus":true
} "", "" । 2. 0"
}

नियम: योजनाओं के पिछड़े-संगत विकास, रजिस्ट्री + अनुबंध परीक्षण।

---

6) एपीआई संस्करण: रणनीतियाँ और नियम

6. 1 संस्करण कहां संग्रहीत करें

पथ संस्करण: '/v1/... '(सिर्फ कैश/रूट)।

शीर्षिका संस्करण: 'स्वीकारें: अनुप्रयोग/vnd. मंच। api + json; संस्करण = 1। 2`.

घटनाएँ: घटना क्षेत्र + रजिस्ट्री में 'स्कीमा _ संस्करण'.

अभ्यास: HTTP के लिए पथ, घटनाओं के लिए, बिंदु क्षमताओं के लिए झंडे की सुविधा।

6. 2 SemVer और परिवर्तन प्रकार

PATCH (मामूली) - रिवर्स डॉकिंग: नए वैकल्पिक क्षेत्र, नए समापन बिंदु, नए प्रकार की घटनाएं।

मेजर - ब्रेकिंग: फ़ील्ड का नाम बदलना, शब्दार्थ बदलना, हटाना। केवल नए '/vN/' और पुराने की कमी के माध्यम से अनुमत।

6. 3 स्थिर अनुबंध (जिसे तोड़ा नहीं जा सकता)

कुंजी पहचान क्षेत्र के नाम और प्रकार ('_ id', 'idempotency _ key').

मौद्रिक मॉडल ('राशि/मुद्रा', सटीकता)।

• स्थिति शब्दार्थ ('अधिकृत', 'श्रेय', 'जब्त', आदि)।
• पहचान: पुनरावृत्ति व्यवहार कड़ाई से परिभाषित किया गया है।

---

7) संगतता और विकास

7. 1 जोड़ें (सुरक्षित)

डिफ़ॉल्ट के साथ नए वैकल्पिक क्षेत्र।

• मौजूदा घटनाओं को बदले बिना नई घटनाएं/समापन बिंदु।
• 'अज्ञात' में फॉलबैक के साथ एनम एक्सटेंशन।

7. 2 परिवर्तन (जोखिम भरा)

फ़ील्ड क़िस्म (संख्या → पंक्ति) बदलें।

• वैकल्पिक → आवश्यक।
• व्यापार तर्क का उलटफेर ('अधिकृत करने से पहले' निपटान ')।
• → एक नए प्रमुख संस्करण और माइग्रेशन गाइड की आवश्

7. 3 मूल्यह्रास

फ़ील्ड/एंडपॉइंट को 'deprecated _ के बाद से चिह्नित किया गया है: 1। 7 ',' हटाया _ इन: 2। 0`.

संचार: रिलीज नोट्स, न्यूज़ लेटर, डिप्रेशन-हेडर ('सनसेट', 'डिप्रेशन')।

सक्रिय साथी सूचनाओं के लिए "पुराने" रास्तों के उपयोग का पता लगाना।

---

8) पहचान और निरंतरता

सभी रिकॉर्डिंग संचालन के लिए 'X-Idempotency-Key' हेडर की आवश्यकता होती है।

शब्दार्थ: एक ही कुंजी के साथ दोहराएं - एक ही परिणाम (एक ही शरीर के साथ 200)।

कुंजी पैरामीटर की संरचना के लिए बाध्य हैं (उदाहरण के लिए, 'बेट _ आईडी + राशि')।

लंबी प्रक्रियाओं पर सागास: 'अधिकृत कमिटमेंट/लॉक सेटलमेंट क्रेडिट'; मुआवजा - 'रोलबैक' घटनाएं।

---

9) पैगिनेशन, फिल्टर, सॉर्टिंग

संकेतक आधारित पृष्ठभूमि (बड़ेधागे के लिए कड़ाई से पसंद किया गया 'पृष्ठ/सीमा')।

एकीकरण: '? कर्सर =... और सीमा = 200 और ऑर्डर = asc '।

उत्तर में: 'अगला _ कर्सर', 'हैव _ मोर'।

फ़िल्टर: समय के अनुसार ('hease _ at _ at _ to/to'), 'किरायेदार _ id', 'game _ id', 'state'.

---

10) स्थान, मुद्राएं, डेटा रेजिडेंसी

ISO-4217 में मुद्रा; सटीकता को योजना ('स्केल'), गणना में संग्रहीत किया जाता है - लघु-इकाइयों (सेंट) में।

लोकाली - बीसीपी 47 ('एन-जीबी', 'पीटी-बीआर')।

प्रत्येक अनुरोध में - 'क्षेत्र'; पीआईआई और नकद लेनदेन क्षेत्रों को पार नहीं करते हैं।

द्वितीय शोकेस में पीआईआई और आरएलएस मास्किंग।

---

11) अवलोकन और सीमा

आवश्यक शीर्षक: 'एक्स-ट्रेस-आईडी', 'एक्स-प्रदाता-आईडी', घटनाओं के साथ सहसंबंध।

मेट्रिक्स: p50/p95/p99 विलंबता, त्रुटि दर (कोड द्वारा), थ्रूपुट, कतार लैग (घटनाओं के लिए)।

दर सीमा: प्रदाता/प्रति ब्रांड; 'रीट्री-आफ्टर' से प्रतिक्रियाएँ।

महत्वपूर्ण परिवर्तनों का WORM ऑडिट (सीमाएं, RTP पूल, जैकपॉट सूत्र)।

---

12) संविदाओं का परीक्षण और गुणवत्ता

अनुबंध परीक्षण (संधि/अन्य): प्रदाता ↔ मंच ↔ घटना उपभोक्ता।

लोड: दरों/बस्तियों का "तूफान"; p95 के लक्ष्य।

अराजकता के मामले: डबल-डिलीवरी, आउट-ऑफ-ऑर्डर, वॉलेट देरी।

सैंडबॉक्स '/सैंडबॉक्स 'काल्पनिक धन और परीक्षण' प्लेयर _ आईडी 'के साथ।

---

13) एसडीके, जनरेटर और प्रलेखन

OpenAPI/AsyncAPI → SDK जनरेशन (टाइपस्क्रिप्ट/जावा/कोटलिन/गो/रस्ट)।

'ऑथोराइज ़/सेटल/रोलबैक', रिट्रेज़और त्रुटि हैंडलिंग के लिए कोड उदाहरण।

अनुरोध/प्रतिक्रिया (कर्ल + JSON), पोस्टमैन/अनिद्रा संग्रह के उदाहरणों के साथ लाइव डॉक।

परिवर्तन प्रकार और संगतता लेबल के साथ चेंजेलॉग।

---

14) माइग्रेशन रोडमैप (उदाहरण)

1. v1। 6 → v1। 7 (माइनर) ने 'बोनस _ स्टेट' फ़ील्ड को 'सेटल' (वैकल्पिक) में जोड़ा।

2. v1। x EOL घोषणा: 6 महीने के लिए - अक्षर + 'Deprecation' हेडर + उपयोग का डैशबोर्ड।

3. v2। 0 (प्रमुख): व्यक्तिगत 'वॉलेट। प्रतिबद्ध '(पूर्व में निहित), नए क्षेत्र' सेटलमेंट _ आईडी 'की आवश्यकता है।

4. माइग्रेशन गाइड: फील्ड मैपिंग, टाइमलाइन, "डबल राइटिंग" का फिचफ्लैग ('v1 '/' v2' इवेंट्स का समानांतर प्रकाशन)।

5. सनसेट v1: नए एकीकरण को अवरुद्ध करना, केवल एसएलए अपवादों के लिए विस्तार करना।

---

15) चेकलिस्ट

प्लेटफॉर्म आर्किटे

• डोमेन संस्थाओं और आक्रमणकारियों का एक ही शब्दकोश है।
• OpenAPI/AsyncAPI + स्कीमा रजिस्ट्री, सेवर, कमी की प्रक्रिया।
• सभी लिखने के कार्यों पर पहचान; कुंजी प्रलेखित हैं।
• एकल त्रुटि मॉडल और कोड।
• धन के तरीकों पर सागास और आउटबॉक्स/सीडीसी।
• दर-सीमा, अवलोकन, WORM ऑडिट।
• सैंडबॉक्स और अनुबंध परीक्षण भागीदारों के लिए उपलब्ध हैं।
• डेटा रेजिडेंसी और आरएलएस/मास्किंग।

प्रदाता के लिए

• मैं हमेशा 'एक्स-ट्रेस-आईडी' और 'एक्स-आइडेम्पोटेंसी-की' भेजता हूं।
• मैं सुरक्षित रूप से दोहराव का अनुरोध करता हूं; मैं युगल नहीं बनाता।
• 'Deprecation/Sunset' का प्रसंस्करण और Changelog पढ़ ना।
• मैं रजिस्ट्री योजनाओं के अनुसार घटनाओं को प्रकाशित/पढ़ता हूं; मैं एक संस्करण रखता हूं।
• मेरी तरफ से पुन: प्रयास/बैकऑफ और डिडुप्लिकेशन है।

---

16) एंटी-पैटर्न (लाल झंडे)

डेटाबेस में शेष/बस्तियों के मैनुअल संपादन।

• घटनाओं को "अतीत" आउटबॉक्स/सीडीसी प्रकाशित कर रहा है।
• कोई पहचान नहीं - डुप्लिकेट भुगतान/डेबिट।
• 'क्षेत्र' को चिह्नित किए बिना विभिन्न क्षेत्रों के पीआईआई/धन का मिश्रण।
• "शांत" एक नए संस्करण और decrement के बिना परिवर्तन।
• SDK मैन्युअल रूप से उत्पन्न (वास्तविक चश्मा के साथ बहाव)।
• फ्लैग और डबल इवेंट राइटिंग के बिना बिग-बैंग माइग्रेशन।

---

एक एकल एपीआई न केवल "एंडपॉइंट्स का संग्रह" है, बल्कि एक पारिस्थितिकी तंत्र अनुबंध है: एक सुसंगत शब्दकोश, स्थिर मौद्रिक आक्रमणकारी, मौखिक घटनाएं, स्पष्ट संगतता नियम और प्रबंधनीय कमी। शब्दार्थ संस्करण, पहचान, आउटबॉक्स/सीडीसी, अवलोकन और मजबूत सुरक्षा पर निर्भर करते हुए, मंच प्रदाताओं को जल्दी और दर्द रहित रूप से जोड़ ता है, और उन्नयन जोखिम से दिनचर्या में बदल जाता है।