API יחיד לספקים: עיצוב, גירסה, תאימות

מאמר מלא

💡 18+. חומר טכני לאינטגרציה וצוותי פלטפורמה. לא שיחה לשחק.

1) מדוע ”API יחיד” ומה זה

API יחיד הוא מפרט וקבוצה של נקודות קצה/אירועים שבאמצעותם כל ספק תוכן (RGS, אולפן חי, קופה, KYC/AML) מתקשר עם הפלטפורמה על פי אותם כללים:

מודל משאבים מאוחד (שחקנים, מפגשים, הימורים, התנחלויות, בונוסים, זכיינים, תשלומים), חוזי אירועים משותפים ומזהים, תקני אבטחה ותאימות לאחור, SDK/כלים כדי להאיץ את האינטגרציה.

המטרה: לצמצם את זמן האינטגרציה, להפחית טעויות ב ”נתיבי כסף” ולספק שדרוגים צפויים.

2) עקרונות עיצוב

1. דומיין-ראשון. ראשית, המילון והאינווריאנטים (קצב, הגדרה, גבולות RG), ואז נקודות סוף.

2. תאימות כברירת מחדל. כל שינוי מתאים כברירת מחדל; שבירת שינויים אך ורק על ידי תהליך.

3. אידמפוטנטיות בכל מקום. כל פקודות הכסף ניתנות לחזרה ללא תופעות לוואי.

4. האירועים הם מקור האמת. Operations # אירועים לאוטובוס; אנליטיקה מקשיבה לאוטובוס, לא מנצחת את OLTP.

5. לפחות זכות ואפס אמון. אסימונים, חתימות, קטעים על ידי מותג/אזור.

6. יכולת תצפית. trace _ id, מודל שגיאה מובן, p95/p99 metrics.

3) מודל משאב (מפושט)

שחקן: platform side player pseudo-ID, geo/curry/RG statuses.

הפעלה: ערוץ בין הספק לפלטפורמה ("session _ id', TTL, geo/limitions).

הימור: אישור/חיוב הימור.

תוצאה עגולה וזכייה באשראי.

בונוס/הימור: בונוס/מצב שיווי משקל.

כל הקופה: תרומות/הפעלות/תשלום.

אירוע: אירועי תחום בלתי משתנים (Kafka/analogues).

מזהים: "terant _ id'," brand _ id', "region", "player _ id'," session _ id', "round _ id'," bet _ id', "settlement _ id'. כל מחרוזת, ייחודית גלובלית (UUID/KSUID/Snowflake), כלולה ביומנים ובאירועים.

4) חוזי API: בקשות, תגובות, טעויות

4. 1 אישור וביטחון

OAuth2 לקוח או mTLS + מבקש חתימת גוף (HMAC/EDSA).

”הימורים: לכתוב”, ”התנחלויות: לכתוב”, ”מפגשים: לקרוא”, ”אירועים: לפרסם”.

כותרות נדרשות בכל בקשה:

”X-Trace-Id',” X-Brand-Id', ”X-Region”, ”X-Idempotency-Key”.

4. 2 דוגמאות לנקודות סוף

יצירת הפעלה


פוסט/v1/מפגשים
{
”player_id":"p_19f3,” ”game_id":"studio:slot_forge_02,” ”מטבע”:” EUR”, ”locale”:” דה דה”, ”אילוצים ”: (”max _ bet ”: 5, ”rg _ flags”: [” self _ exclusion”: false ]
}
→ 201
{
"session_id":"s_456," expires_at":"2025-10-23T19:10:00Z "
}

אישור קצב (החזק)


פוסט/v1/הימורים/לאשר
כותרות: X-Idempotency-Key: bet_r_8c12_1
{
”session_id":"s_456,” ”bet_id":"b_001,” ”round_id":"r_8c12,” ”כמות”: 00, ”מטבע”:” EUR”
}
* 200 "סטטוס": "מורשה", "hold _ id':" h _ zz1 "

התיישבות


פוסט/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 "סטטוס": "קרדיט", "הסדר _ id':" st _ 77 "

4. 3 שגיאות (מודל יחיד)

קוד: ”Duplicate”, IDEMPOTENCY _ MISMATCH, ”INVALID _ STATE”, ”AUTH _ נכשל”.

”Message”: קצר עבור האדם.

”ניתן לניסיון”: ”אמת/שקר”.

"trace _ id': לחפש את היומנים.

דוגמה:


סכסוך 409
{
קוד: ”DUPLICATE”, ”הודעה”: ”בית כבר מורשה עם כמות שונה”, ”מחדש”: שקר, ”trace_id":"tr_a1b2c3”
}

5) אוטובוס אירועים ומעגלים

5. 1 נושאים בסיסיים

'Player. רשום, 'ישיבה. התחיל	סוף &fost
'bet. מורשה	פשרה
"בונוס. הונפקה	נצרך
"וויאג 'ר. התקדמות. עדכון &posted
'ג' קט. תרומה	מופעל
'rg. הגבלה. פגע ',' rg. reality_check'
"וואלט. חיוב. ", ארנק. קרדיט. &pos;

5. 2 סכמת אירועים (סכימת Avro/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, ”מטען”:
”round_id":"r_8c12,” ”הימור ”: [”כמות”: 1. 00, ”מטבע”: ”EUR”, ”לנצח”: [”סכום”: 14. 60, ”מטבע”: ”EUR”? ”,” in_bonus":true
idempotency_key":"bet_r_8c12_1, ”schema_version":"1”. 2. 0"
}

כללים: אבולוציה התואמת לאחור של תוכניות, בדיקות רישום + חוזה.

6) גרסת API: אסטרטגיות וחוקים

6. 1 היכן לאחסן את הגרסה

גרסת מסלול: '/v1/... (רק מטמון/מסלול).

גרסת כותרת: "קבל: application/vnd. פלטפורמה. אפי + ג 'סון; גרסה = 1. 2`.

אירועים: ”schema _ version” ברישום שדה האירועים +.

תרגול: נתיב עבור HTTP, schema_version עבור אירועים, דגלים עבור יכולות נקודה.

6. 2 SEMVER וסוגי שינוי

מעגן הפוך: שדות אופציונליים חדשים, נקודות קצה חדשות, סוגים חדשים של אירועים.

שובר סרן: שינוי שמות שדות, שינוי סמנטיקה, מחיקה. מותר רק דרך '/vN/' החדש ודלדול הישן.

6. 3 חוזים יציבים (שלא ניתן לשבור)

שמות וסוגים של שדות זיהוי מפתח ("_ id'," idempotency _ key ").

מודל מוניטרי (”כמות/מטבע”, דיוק).

סמנטיקה סטטוס ('מורשה', 'קרדיט', 'מבוטל', וכו ').

אידמפוטנטיות: התנהגות החזרה מוגדרת בקפדנות.

7) תאימות ואבולוציה

7. 1 הוסף (בטוח)

שדות אופציונליים חדשים עם ברירות מחדל.

אירועים/נקודות סוף חדשות ללא שינוי אלה הקיימים.

הארכת אנום עם נסיגה לא ידועה.

7. 2 שינויים (מסוכנים)

שינוי סוג השדה (מספר = קו).

אופציונלי לאגר נדרש.

היפוך הלוגיקה העסקית (”ליישב” לפני ”לאשר”).

יש צורך בגרסה מרכזית חדשה ומדריך הגירה.

7. 3 ביטול קישורName

שדה/נקודת קצה מסומן ב- deeprecated _ מאז: 1. 7 ',' הוסר _ in: 2. 0`.

תקשורת: הערות שחרור, עלון חדשות, כותרות ירידות (”Sunset”, ”Deprecation”).

התחקות אחר השימוש במסלולים ”מיושנים” להודעות פרטנר פרואקטיביות.

8) אידמפוטנטיות ועקביות

הכותרת 'X-Idempotency-Key' נדרשת לכל פעולות ההקלטה.

סמנטיקה: לחזור עם אותו מפתח = תוצאה זהה (200 עם אותו גוף).

מפתחות קשורים להרכב של פרמטרים (לדוגמה, 'bet _ id + sume').

Sagas על תהליכים ארוכים: 'לאשר Implox/lock act accredit'; פיצוי - אירועי 'rollback'.

9) עבודת אלילים, מסננים, מיון

pagination מבוסס סמן (page/limit) עבור אשכולות גדולים.

איחוד: ”?” הסמן = & גבול = 200 & סדר = asc.

בתשובה: ”הבא _ הסמן”, ”יש _ יותר”.

מסננים: בזמן (”התרחש _ at _ from/to”), ”terenant _ id',” game _ id', ”status”.

10) מקומות, מטבעות, תושבות נתונים

מטבע ISO-4217; הדיוק מאוחסן בתכנית ('סולם'), חישובים - ביחידות קטנות (סנט).

לוקאלי - BCP 47 (”en-GB”, ”pt-BR”).

בכל בקשה - 'אזור'; מח "ש ועסקאות מזומנים לא חוצים אזורים.

PII ו RLS מסווה בתצוגות BI.

11) יכולת תצפית וגבולות

כותרות נדרשות: ”X-Trace-Id',” X-Deliver-Id', מתאם עם אירועים.

מטריצות: p50/p95/p99 latency, שיעור שגיאה (על ידי קודים), תפוקה, תור lag (לאירועים).

מגבלות קצב: לכל ספק/לכל מותג; תגובות מ ”Retry-After”.

ביקורת תולעת של שינויים קריטיים (גבולות, בריכות RTP, נוסחאות כל הקופה).

12) בדיקות ואיכות של חוזים

מבחני חוזה (Pact/other): ספק ↔ פלטפורמה ↔ צרכני אירועים.

העומס: ”סערה” של תעריפים/התנחלויות; מטרות של p95.

מקרי כאוס: משלוח כפול, מחוץ לסדר, עיכובים בארנק.

ארגז חול "/ארגז חול "עם כסף פיקטיבי ומבחן" player _ id'.

13) SDK, גנרטורים ותיעוד

OpenAPI/ASyncAPI * SDK deneration (TypeScript/Java/Kotlin/Go/Rust).

דוגמאות קוד ל ”אישור/יישוב/rollback”, מגשים מחדש וטיפול בשגיאות.

Live dock עם דוגמאות של בקשה/תגובה (curl + JSON), אוסף Postman/Insomnia.

צ 'אנגלוג עם סוגי שינוי ותוויות תאימות.

14) מפת דרכים נדידה (דוגמה)

1. V1. # 6 v1. 7 (מינור) הוסף שדה ”בונוס _ מדינה” כדי ”להתיישב” (אופציונלי).

2. V1. הודעה X EOL: במשך 6 חודשים - אות + ”Deprecation” כותרת + לוח מחוונים של שימוש.

3. V2. 0 (מייג 'ור): הפרט' wallet. להתחייב (לשעבר מרומז), שדה חדש "יישוב _ id' נדרש.

4. מדריך נדידה: מיפוי שדה, ציר זמן, פיצ 'פלאג של ”כתיבה כפולה” (פרסום מקביל של ”v1 ”/” v2” אירועים).

5. שקיעה v1: חסימת אינטגרציות חדשות, מתארכת רק לחריגות SLA.

15) רשימות בדיקה

עבור אדריכלי פלטפורמה

[ ] קיים מילון יחיד של ישויות ממלכתיות וחדשניות.

[ ] OpenAPI/ASyncAPI + Schema Registry, semver, processions.

[ ] Idempotency על כל פעולות כתיבה; מפתחות מתועדים.

[ ] מודל שגיאות וקודים בודדים.

[ ] סאגות ומרכז לבקרת מחלות בדרכים כספיות.

[ מגבלות קצב ], יכולת תצפית, ביקורת תולעת.

[ ] ארגז חול ובדיקות חוזה זמינים לשותפים.

[ תושבות ] דאטה ו-RLS/מיסוך.

עבור הספק

[ ] אני תמיד שולח "X-Trace-Id' ו-" X-Idempotency-Key ".

[ ] אני מעבד בקשות חזרה בבטחה; אני לא יוצר כפילים.

[ עיבוד ] 'Disprecation/Sunset' וקריאת Changelog.

[ ] אני מפרסם/קורא אירועים לפי מזימות הרישום; יש לי גרסה.

[ ] יש לי מחדש/חזרה ושכפול בצד שלי.

16) אנטי דפוסים (דגלים אדומים)

עריכה ידנית של מאזן/התנחלויות במאגר הנתונים.

פרסום אירועים ”בעבר” תיבת אאוטבוקס/CDC.

אין אידמפוטנטיות * לשכפל תשלומים/חיובים.

ערבוב פיל/כסף של אזורים שונים מבלי לסמן 'אזור'.

”שקט” שינוי שבירה ללא גרסה חדשה והשלמה.

יצירת SDK ידנית (סחיפה עם מפרט אמיתי).

נדידת מפץ-גדול ללא דגלי תכונה וכתיבת אירועים כפולים.

API יחיד הוא לא רק ”אוסף של נקודות קצה”, אלא גם חוזה מערכת אקולוגית: מילון עקבי, אינווריאנטים כספיים יציבים, אירועים מומצאים, כללי תאימות ברורים, וירידות הניתנות לניהול. הסתמכות על גירסה סמנטית, אידמפוטנטיות, תיבה/CDC, תצפית וביטחון חזק, הפלטפורמה מחברת ספקים במהירות וללא כאבים, ושדרוגים הופכים מסיכון לשגרה.