API واحد برای ارائه دهندگان: طراحی، نسخه، سازگاری

مقاله کامل

💡 18+. مواد فنی برای تیم های ادغام و پلت فرم. فراخوانی برای بازی نیست.

1) چرا «API تک» و آنچه در آن است

یک API تنها یک مشخصات و مجموعه ای از نقاط پایانی/حوادث است که از طریق آن هر ارائه دهنده محتوا (RGS، استودیوی زنده، جکپات، KYC/AML، وابسته) با پلت فرم با توجه به قوانین مشابه ارتباط برقرار می کند:

مدل منابع یکپارچه (بازیکنان، جلسات، شرط ها، شهرک ها، پاداش ها، جکپات ها، پرداخت ها)، قراردادهای رویداد مشترک و شناسه ها، استانداردهای سازگاری امنیتی و عقب مانده، SDK/ابزار برای سرعت بخشیدن به ادغام.

هدف: کاهش زمان ادغام، کاهش اشتباهات در «مسیرهای پول» و ارائه ارتقاء قابل پیش بینی است.

2) اصول طراحی

1. اول دامنه. اول، فرهنگ لغت و ثابت (نرخ، تنظیم، محدودیت RG)، و سپس نقاط پایانی.

2. سازگاری به طور پیش فرض. هر گونه تغییر به طور پیش فرض سازگار است ؛ شکستن تغییرات به شدت توسط روند.

3. بی تفاوتی در همه جا تمام دستورات پولی بدون عوارض جانبی قابل تکرار هستند.

4. حوادث منبع حقیقت هستند. عملیات → حوادث به اتوبوس; تجزیه و تحلیل به اتوبوس گوش می دهد، نه ضرب و شتم OLTP.

5. کمترین امتیاز و اعتماد صفر نشانه ها، امضاها، تقسیم بندی بر اساس نام تجاری/منطقه.

6. قابل مشاهده بودن End-to-end 'trace _ id'، مدل خطای قابل فهم، معیارهای p95/p99.

3) مدل منابع (ساده شده)

بازیکن: بازیکن سمت پلت فرم شبه ID، وضعیت جغرافیایی/ارز/RG.

جلسه: یک کانال بین ارائه دهنده و پلت فرم ('session _ id'، TTL، جغرافیایی/محدودیت ها).

شرط بندی: مجوز شرط بندی/بدهی.

حل و فصل: نتیجه دور و برنده اعتبار.

پاداش/شرط بندی: وضعیت تعادل پاداش/vager.

برنده تمام پولها: کمک/باعث/پرداخت.

رویداد: رویدادهای دامنۀ تغییرناپذیر) کافکا/آنالوگ (.

شناسه ها: 'tenant _ id'، 'brand _ id'، 'region'، 'player _ id'، 'session _ id'، 'round _ id'، 'bet _ id'، 'settlement _ id'. تمام رشته ها، در سطح جهانی منحصر به فرد (UUID/KSUID/Snowflake)، در سیاهههای مربوط و حوادث گنجانده شده است.

4) قراردادهای API: درخواست ها، پاسخ ها، خطاها

4. 1 مجوز و امنیت

OAuth2 اعتبار مشتری یا mTLS + امضای بدن درخواست (HMAC/EdDSA).

Скоупы вида: «شرط: نوشتن»، «شهرک سازی: نوشتن»، «جلسات: خواندن»، «رویدادها: انتشار».

هدرها در هر درخواست مورد نیاز است:

«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»:» DE», «محدودیت «: {«max _ bet «: 5, «rg _ flags»: [» self _ exclusion»: نادرست]}
}
→ 201
{
«session_id":"s_456,» «expires_at":"2025-10-23T19:10:00Z»
}

مجوز نرخ (نگه دارید)


POST/v1/شرط/اجازه
هدر: X-idempotency-کلید: bet_r_8c12_1
{
"session_id":"s_456," "bet_id":"b_001," "round_id":"r_8c12," مقدار ": {" مقدار ": 2. 00، «ارز»:» EUR»}
}
→ 200 {«وضعیت «: «مجاز»,» hold _ id»:» h _ zz1»}

حل و فصل


پست/v1/شرط/حل و فصل
هدر: X-idempotency-کلید: 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 خطا (مدل تک)

'کد': машинное имя ('RG _ BLOCK'، 'LIMIT _ EXCESSED'، 'DUPLICATE'، 'IDEMPOTENCY _ MISMATCH'، 'INVALID _ STATE'، 'AUTH _ FAILED').

«message»: مختصر برای شخص.

'retryable': 'درست/نادرست'.

'trace _ id': برای جستجو در سیاهههای مربوط.

به عنوان مثال:


409 درگیری
{
«code «: «DUPLICATE», «message»:» Bet already authorized with a different amount», «retryable»: غلط, «trace_id":"tr_a1b2c3»
}

5) اتوبوس رویداد و مدار

5. 1 موضوعات اساسی

بازی کن. ثبت نام «،» جلسه. شروع کرد	تمام شد
خوب شد. مجاز است	مستقر شد
سلام. صادر شده	مصرف شده
شرط میبندم. پیشرفت. به روز شده
جکپات. کمک های مالی	باعث شد
آ ره. محدود کردن RG 'ضربه. reality_check'
تمام شد. دبیت، کیف پول. اعتبار.

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/... (فقط کش/مسیر).

نسخه سربرگ: 'Accept: application/vnd. پلت فرم. API + JSON ؛ نسخه = 1 2`.

رویدادها: «schema _ version» در فیلد رویداد + رجیستری.

تمرین: مسیر برای HTTP، schema_version برای رویدادها، ویژگی های پرچم برای قابلیت های نقطه.

6. 2 SemVer و انواع تغییر

PATCH (جزئی) - اتصال معکوس: زمینه های اختیاری جدید، نقاط پایانی جدید، انواع جدیدی از رویدادها.

MAJOR - شکستن: تغییر نام زمینه ها، تغییر معانی، حذف. فقط از طریق «/vN/» جدید و تخلیه قدیمی مجاز است.

6. 3 قراردادهای پایدار (که نمی توانند شکسته شوند)

نام و انواع فیلدهای شناسایی کلید ('_ id', 'idempotency _ key').

مدل پولی («مقدار/ارز»، دقت).

معناشناسی وضعیت («مجاز»، «اعتبار»، «جریمه» و غیره).

Idempotency: رفتار تکرار به شدت تعریف شده است.

7) سازگاری و تکامل

7. 1 اضافه کردن (امن)

زمینه های اختیاری جدید با پیش فرض.

رویدادها/نقاط پایانی جدید بدون تغییر موارد موجود.

پسوند Enum با عقب نشینی در «ناشناخته».

7. ۲ تغییرات (ریسک)

نوع فیلد را تغییر دهید (number → line).

اختیاری → مورد نیاز

معکوس کردن منطق کسب و کار («حل و فصل» قبل از «مجاز»).

→ نیاز به یک نسخه اصلی جدید و راهنمای مهاجرت.

7. 3 کاهش ارزش

فیلد/نقطه پایانی با 'مشخص شده است: 1. 7 '،' حذف شده در: 2. 0`.

ارتباطات: یادداشت های انتشار، خبرنامه، هدر های تخفیف («غروب آفتاب»، «تخفیف»).

ردیابی استفاده از مسیرهای «قدیمی» برای اطلاعیه های شریک فعال.

8) بی نظمی و سازگاری

هدر 'X-Idempotency-Key' برای تمام عملیات ضبط مورد نیاز است.

Semantics: تکرار با همان کلید → همان نتیجه (200 با همان بدن).

کلیدها به ترکیبی از پارامترها محدود می شوند (به عنوان مثال، «bet _ id + مقدار»).

Sagas در فرایندهای طولانی: «authorize → commit/lock → settle → credit»; جبران خسارت - «بازگشت» حوادث.

9) صفحه بندی، فیلتر، مرتب سازی

صفحه بندی مبتنی بر مکان نما (به شدت ترجیح «صفحه/حد» برای موضوعات بزرگ).

وحدت: '؟ مکاننما =... & limit = 200 & ترتیب = asc '.

در پاسخ: 'next _ cursor', 'has _ more'.

فیلترها: با زمان ('رخ داده است _ at _ from/to')، 'tenant _ 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 تاخیر، نرخ خطا (توسط کد)، توان، تاخیر صف (برای حوادث).

محدودیت نرخ: در هر ارائه دهنده/در هر نام تجاری ؛ پاسخ های «تلاش دوباره»

ممیزی WORM از تغییرات بحرانی (محدودیت ها، استخرهای RTP، فرمول های جکپات).

12) تست و کیفیت قراردادها

تست های قرارداد (Pact/others): ارائه دهنده ↔ پلت فرم ↔ مصرف کنندگان رویداد.

بار: «طوفان» نرخ/شهرک ؛ اهداف P95

موارد هرج و مرج: تحویل دوگانه، عدم سفارش، تاخیر کیف پول.

Sandbox «/sandbox »با پول ساختگی و تست« player _ id ».

13) SDK، ژنراتور و اسناد و مدارک

OpenAPI/AsyncAPI → تولید SDK (TypeScript/Java/Kotlin/Go/Rust).

مثالهای کد برای «authorize/settle/rollback»، retrays و مدیریت خطا.

حوض زنده با نمونه هایی از درخواست/پاسخ (حلقه + JSON)، مجموعه پستچی/بی خوابی.

Changelog با انواع تغییر و برچسب سازگاری.

14) نقشه راه مهاجرت (مثال)

1. V1 6 → v1. 7 (جزئی) فیلد «bonus _ state» را برای «حل و فصل» (اختیاری) اضافه کرد.

2. V1 x اعلامیه EOL: به مدت 6 ماه - نامه + عنوان «استهلاک» + داشبورد استفاده.

3. V2. 0 (عمده): فردی 'wallet. commit '(قبلا ضمنی)، فیلد جدید' settlement _ id 'مورد نیاز است.

4. راهنمای مهاجرت: نقشه برداری درست، جدول زمانی، fichflag از «نوشتن دو» (انتشار موازی رویدادهای «v1 »/« v2»).

5. Sunset v1: مسدود کردن یکپارچگی جدید، فقط برای استثنائات SLA گسترش می یابد.

15) چک لیست

برای معماران پلت فرم

یک فرهنگ لغت واحد از نهادهای دامنه و ناوردا وجود دارد.
OpenAPI/AsyncAPI + طرح رجیستری، semver، روند کاهش.
Idempotency در تمام عملیات نوشتن ؛ کلیدها مستند شده است.
مدل خطا و کدهای تک.
Sagas و outbox/CDC در راه پول.
میزان محدودیت، مشاهده، حسابرسی WORM.
Sandbox و تست قرارداد برای شرکا در دسترس هستند.
اقامت داده ها و RLS/ماسک.

برای ارائه دهنده

من همیشه «X-Trace-Id» و «X-Idempotency-Key» را ارسال می کنم.
من درخواست تکرار را با خیال راحت پردازش می کنم ؛ من دوگانهها را نمیسازم.
پردازش «استهلاک/غروب آفتاب» و خواندن Changelog.
من رویدادها را با توجه به طرح های رجیستری منتشر می کنم/می خوانم ؛ من يه نسخه ازش دارم
من تلاش مجدد/عقب نشینی و deduplication در کنار من.

16) ضد الگوهای (پرچم قرمز)

ویرایش دستی توازن/شهرک در پایگاه داده.

انتشار رویدادهای «گذشته» outbox/CDC.

بدون idempotency → پرداخت های تکراری/بدهی ها.

مخلوط کردن PII/پول از مناطق مختلف بدون مارک «منطقه».

تغییرات شکستن «آرام» بدون نسخه جدید و کاهش.

تولید SDK به صورت دستی (رانش با مشخصات واقعی).

مهاجرت بیگ بنگ بدون پرچم ویژگی و نوشتن رویداد دوگانه.

یک API تنها «مجموعه ای از نقاط پایانی» نیست، بلکه یک قرارداد اکوسیستم است: یک فرهنگ لغت سازگار، ثابت پولی ثابت، رویدادهای نسخه، قوانین سازگاری روشن و احکام قابل کنترل. با تکیه بر نسخه معنایی، idemotency، outbox/CDC، قابلیت مشاهده و امنیت قوی، این پلت فرم ارائه دهندگان را به سرعت و بدون دردسر متصل می کند و ارتقاء از خطر به روال تبدیل می شود.