واجهة برمجة تطبيقات واحدة لمقدمي الخدمات: التصميم، الإصدار، التوافق

مقالة كاملة

💡 18+. مواد تقنية لأفرقة التكامل والمنبر. ليست دعوة للعب.

1) لماذا «واجهة برمجة التطبيقات الفردية» وما هي

واجهة برمجة التطبيقات الواحدة هي مواصفات ومجموعة من نقاط النهاية/الأحداث التي من خلالها يتواصل أي مزود محتوى (RGS، الاستوديو المباشر، الجائزة الكبرى، KYC/AML، الشركات التابعة) مع النظام الأساسي وفقًا لنفس القواعد:

نموذج الموارد الموحدة (اللاعبون، الجلسات، الرهانات، التسويات، المكافآت، الجوائز الكبرى، المدفوعات)، عقود الأحداث المشتركة ومحددات الهوية، معايير التوافق الأمني والمتخلف، SDK/الأدوات لتسريع عمليات التكامل.

الهدف: تقليل وقت الاندماج وتقليل الأخطاء في «مسارات المال» وتوفير ترقيات يمكن التنبؤ بها.

2) مبادئ التصميم

1. المجال أولاً. أولاً، القاموس والثوابت (معدل، تعيين، حدود RG)، ثم نقاط النهاية.

2. التوافق افتراضيًا. أي تغيير متوافق افتراضيًا ؛ كسر التغييرات بدقة عن طريق العملية.

3. الفراغ في كل مكان. جميع الأوامر المالية قابلة للتكرار دون آثار جانبية.

4. الأحداث هي مصدر الحقيقة. عمليات → الأحداث إلى الحافلة ؛ التحليلات تستمع إلى الحافلة، ولا تتفوق على OLTP.

5. أقل امتياز وصفر ثقة. الرموز والتوقيعات والتجزئة حسب العلامة التجارية/المنطقة.

6. إمكانية الملاحظة. «trace _ id»، نموذج خطأ مفهوم، p95/p99.

3) نموذج الموارد (مبسط)

المشغل: Platform side player pleudo-ID, geo/currency/RG statuses.

الجلسة: قناة بين مقدم الخدمة والمنصة ('session _ id', TTL, geo/restrictions).

الرهان: رهان الإذن/الخصم.

التسوية: نتيجة الجولة والفوز بالائتمان.

المكافأة/الرهان: حالة رصيد المكافأة/التباهي.

الجائزة الكبرى: المساهمات/المشغلات/المدفوعات.

الحدث: أحداث المجال دون تغيير (كافكا/نظائر).

المعرفات: «مستأجر _ معرف»، «علامة تجارية _ معرف»، «منطقة»، «مشغل _ معرف»، «جلسة _ معرف»، «جولة _ معرف»، «رهان _ معرف»، «تسوية _ معرف». الكل - سلسلة فريدة من نوعها على مستوى العالم (UUID/KSUID/Snowflake)، مدرجة في جذوع الأشجار والأحداث.

4) عقود API: الطلبات والردود والأخطاء

4. 1 الإذن والأمن

OAuth2 أوراق اعتماد العميل أو mTLS + توقيع هيئة الطلب (HMAC/EdDSA).

Скоупы вида: «الرهانات: الكتابة»، «التسويات: الكتابة»، «الجلسات: القراءة»، «الأحداث: النشر».

الرؤوس مطلوبة في كل طلب:

«X-Trace-Id' و» X-Brand-Id' و «X-Region» و «X-Idempotency-Key».

4. 2 أمثلة على نقاط النهاية

إنشاء الدورة


POST/v1/sessions
{
"player_id":"p_19f3," game_id":"studio:slot_forge_02, "" العملة ":" EUR "،" locale ":" de-DE "،" restrictions': {"max _ bet": 5، "rg _ flags': [" self _ exclusion ": fall]}
}
→ 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، «العملة»:» اليورو»}
}
→ 200 {«الحالة «: «المأذون به»،» عقد _ معرف»:» h _ zz1»}

تسوية


POST/v1/bets/settle
الرؤوس: X-Idempotency-Key: settle_r_8c12_1
{
"bet_id":"b_001," round_id":"r_8c12, "" الفوز ": {" المبلغ ": 14. 60، "العملة":" اليورو"}، "bonus_state":{"in_bonus":true,"freespins_left":7}
}
→ 200 {"status':" credited "," settlement _ id ":" st _ 77 "}

4. 3 أخطاء (نموذج واحد)

«الرمز»: машинное имя ('RG _ BLOCK'، 'LIME _ EXCEDED'، 'DUPLICATE'، 'IDEMPOTENCY _ MISMATCH'، 'INVALIIIED ED E E E TE E EE E TE E E E TORE E E TEEEEEELLLAAALLAALLLELLAEEAAALEAALAEELLLLLLLLLEEEEEEI

«رسالة»: موجز للشخص.

«قابل للتجربة»: «صحيح/خاطئ».

"تتبع _ id': للبحث في السجلات.

مثال:


409
{
«رمز «: «DUPLICE»، «رسالة»:» الرهان المصرح به بالفعل بمبلغ مختلف»، «قابل للتجربة»: خاطئ، «trace_id":"tr_a1b2c3»
}

5) الحافلات والدوائر الفعالة

5. 1 المواضيع الأساسية

اللعب. '،' جلسة. بدأت	انتهى "
'bet. مأذون به	تسوية
«بونس». صدر	المستهلكة
'الرهان. التقدم المحرز. تم تحديثها "
'jackpot. مساهمة	إطلاق
'rg. حد. ضرب '،' rg. reality_check'
'wallet. الخصم. '،' المحفظة. الائتمان ".

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، «العملة»:» اليورو»}، «الفوز «: {«المبلغ»: 14. 60، "العملة":" اليورو"}، "in_bonus":true
}، "idempotency_key":"bet_r_8c12_1," "schema_version":"1. 2. 0"
}

القواعد: التطور المتوافق مع الخلفية للمخططات، واختبارات التسجيل + العقود.

6) نسخة واجهة برمجة التطبيقات: الاستراتيجيات والقواعد

6. 1 مكان تخزين النسخة

نسخة المسار: '/v1/... (مجرد مخبأ/طريق).

نسخة الرأس: 'قبول: طلب/فند. منصة. api + json; النسخة = 1. 2`.

الأحداث: 'schema _ version' in the event field + registry.

الممارسة: مسار HTTP، schema_version للأحداث، يتميز بأعلام لقدرات النقاط.

6. 2 SemVer وأنواع التغيير

PATCH (ثانوي) - الالتحام العكسي: حقول اختيارية جديدة، نقاط نهاية جديدة، أنواع جديدة من الأحداث.

MAJOR - كسر: إعادة تسمية الحقول، تغيير الدلالات، الحذف. مسموح به فقط من خلال '/vN/' الجديد واستنفاد القديم.

6. 3 عقود ثابتة (لا يمكن كسرها)

أسماء وأنواع مجالات تحديد الهوية الرئيسية ('_ id'، 'idempotency _ key').

النموذج النقدي ('المبلغ/العملة'، الدقة).

دلالات الحالة («مصرح بها»، «مقيدة»، «مصادرة»، إلخ).

الخصوصية: يتم تعريف سلوك التكرار بدقة.

7) التوافق والتطور

7. 1 يضاف (آمن)

حقول اختيارية جديدة مع التخلف عن السداد.

أحداث/نقاط نهاية جديدة دون تغيير الأحداث القائمة.

امتداد Enum مع احتياطي في «غير معروف».

7. 2 التغييرات (محفوفة بالمخاطر)

غير نوع الحقل (رقم → خط).

→ الاختيارية المطلوبة.

عكس منطق العمل («تسوية» قبل «إذن»).

→ بحاجة إلى نسخة رئيسية جديدة ودليل للهجرة.

7. 3 الاستنكار

تم وضع علامة على الحقل/نقطة النهاية بـ «مفككة» منذ: 1. 7 '،' إزالة _ في: 2. 0`.

الاتصال: ملاحظات الإصدار، النشرة الإخبارية، الاستنكار - الرؤوس ('Sunset'،' Deprecation ').

تتبع استخدام المسارات «القديمة» لإخطارات الشركاء الاستباقية.

8) الخصوصية والاتساق

مطلوب رأس «X-Idempotency-Key» لجميع عمليات التسجيل.

الدلالات: كرر بنفس المفتاح → نفس النتيجة (200 بنفس الجسم).

ترتبط المفاتيح بتكوين المعلمات (على سبيل المثال، «الرهان _ id + الكمية»).

Sagas على العمليات الطويلة: «يأذن → الالتزام/القفل → تسوية الائتمان →» ؛ التعويض - أحداث «التراجع».

9) التثبيت، المرشحات، الفرز

التثبيت القائم على المؤشر («الصفحة/الحد» المفضل تمامًا للخيوط الكبيرة).

التوحيد: '؟ المؤشر =... & lime = 200 & order = asc '.

في الإجابة: «المؤشر التالي»، «لديه _ المزيد».

المرشحات: حسب الوقت ("حدث _ at _ from/to")، "المستأجر _ id"، "game _ id'،" الحالة ".

10) المواقع والعملات والإقامة في مجال البيانات

العملة ISO-4217 ؛ يتم تخزين الدقة في المخطط («مقياس»)، الحسابات - بالوحدات الثانوية (سنتات).

Locali - BCP 47 ('en-GB'، 'pt-BR').

في كل طلب - 'المنطقة' ؛ لا تعبر PII والمعاملات النقدية المناطق.

قناع PII و RLS في عروض BI.

11) إمكانية الرصد والحدود

العناوين المطلوبة: "X-Trace-Id" و "X-Provider-Id'، علاقة مع الأحداث.

المقاييس: زمن الانتظار p50/p95/p99، معدل الخطأ (حسب الرموز)، الإنتاجية، تأخر الانتظار (للأحداث).

حدود الأسعار: لكل مزود/لكل علامة تجارية ؛ ردود من «Retry-After».

مراجعة WORM للتغييرات الحرجة (الحدود، مجمعات RTP، صيغ الفوز بالجائزة الكبرى).

12) اختبار العقود وجودتها

اختبارات العقد (Pact/others): موفر ↔ منصة ↔ مستهلكي الأحداث.

الحمل: «عاصفة» الأسعار/المستوطنات ؛ أهداف الفقرة 95.

حالات الفوضى: التسليم المزدوج، خارج الطلب، تأخير المحفظة.

Sandbox '/sandbox 'بأموال وهمية واختبار "player _ id'.

13) SDK والمولدات والوثائق

OpenAPI/AsyncAPI → جيل SDK (TypeScript/Java/Kotlin/Go/Rust).

أمثلة رمزية لـ «التفويض/الاستقرار/التراجع»، إعادة التصوير، ومعالجة الخطأ.

رصيف مباشر مع أمثلة على الطلب/الاستجابة (تجعيد + JSON)، مجموعة Postman/Insomnia.

Changelog مع أنواع التغيير وملصقات التوافق.

14) خارطة طريق الهجرة (مثال)

1. v1. 6 → v1. 7 (طفيفة) تمت إضافة حقل «المكافأة _ الدولة» إلى «التسوية» (اختياري).

2. v1. x إعلان EOL: لمدة 6 أشهر - حرف + رأس «Deprecation» + لوحة القيادة للاستخدام.

3. v2. 0 (رئيسي): ممر فردي. ارتكب "(كان ضمنيا في السابق)، يلزم" تسوية - هوية "ميدانية جديدة.

4. دليل الهجرة: رسم الخرائط الميدانية، الجدول الزمني، fichflag of «double writing» (نشر مواز لأحداث 'v1 '/' v2').

5. Sunset v1: منع عمليات التكامل الجديدة، والامتداد فقط لاستثناءات SLA.

15) القوائم المرجعية

لمهندسي المنصات

هناك قاموس واحد لكيانات المجال والثوابت.
OpenAPI/AsyncAPI + Schema Registry، semver، عملية التخفيضات.
الخصوصية في جميع عمليات الكتابة ؛ المفاتيح موثقة.
نموذج ورموز خطأ واحد.
Sagas and outbox/CDC on Money Ways.
حدود المعدل، إمكانية الملاحظة، مراجعة WORM.
اختبارات صندوق الرمل والعقود متاحة للشركاء.
الإقامة في البيانات و RLS/القناع.

لمزود الخدمة

أرسل دائمًا «X-Trace-Id» و «X-Idempotency-Key».
أقوم بتجهيز طلب التكرار بأمان ؛ أنا لا أصنع الزوجي.
معالجة «الاستنكار/غروب الشمس» وقراءة Changelog.
أنشر/أقرأ الأحداث وفقًا لمخططات السجل ؛ أنا أحتفظ بنسخة.
لدي إعادة المحاولة/التراجع والتفريغ من جانبي.

16) الأنماط المضادة (الأعلام الحمراء)

تعديلات يدوية للأرصدة/التسويات في قاعدة البيانات.

نشر الأحداث «السابقة» outbox/CDC.

لا يوجد اختصاص → ازدواجية في المدفوعات/الديون.

مزج الأرقام القياسية لأسعار الاستهلاك/الأموال في مختلف المناطق دون وضع علامات على 'المنطقة'.

تغييرات كسر «هادئة» بدون إصدار جديد وانخفاض.

توليد SDK يدويًا (الانجراف بمواصفات حقيقية).

هجرات كبيرة بدون أعلام مميزة وكتابة أحداث مزدوجة.

إن واجهة برمجة التطبيقات الواحدة ليست فقط «مجموعة من نقاط النهاية»، ولكنها عقد نظام بيئي: قاموس متسق، وثوابت نقدية مستقرة، وأحداث متحققة، وقواعد توافق واضحة، وانخفاضات يمكن التحكم فيها. بالاعتماد على الإصدار الدلالي، والخصوصية، والخروج/مراكز السيطرة على الأمراض والوقاية منها، وإمكانية الملاحظة والأمان القوي، تربط المنصة مقدمي الخدمة بسرعة وبدون ألم، وتتحول الترقيات من مخاطر إلى روتينية.