عمليات واجهة برمجة التطبيقات

(القسم: العمليات والإدارة)

1) الغرض والمبادئ

واجهة برمجة التطبيقات هي «الطبقة التشغيلية» للنظام البيئي: أي شيء غير آلي من خلال عقد يتحول إلى عمل يدوي ومخاطر.

• العقد أولاً: المواصفات الأولى (OpenAPI/JSON Schema/AsyncAPI)، ثم التنفيذ.
• افتراضي آمن: الحد الأدنى من النطاقات، TTL القصير، TLS/التوقيعات المتبادلة.
• يمكن ملاحظته: التعقب من طرف إلى طرف ومقاييس جيش تحرير السودان.
• الأحمق: إعادة التشغيل آمنة.
• متوافقة مع الوراء: التطور دون تغييرات «كسر».
• قابل للمراجعة: حقائق مؤكدة بشكل مشفر (إيصالات).

2) العقود والنماذج (مرجع)

واجهة برمجة التطبيقات المفتوحة للطلبات المتزامنة ؛ AsyncAPI للأحداث/خطوط الويب.
الحقول المطلوبة في كل مورد هي «id» و «version» و «created _ at' و» updated _ at' و «region» و «trace _ id».

مثال على جزء من العقد

yaml paths:
/payments/payouts:
post:
operationId: createPayout requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutRequest'
responses:
"202": { $ref: '#/components/responses/AcceptedWithReceipt' }
headers:
Idempotency-Key:
schema: { type: string }
required: true components:
responses:
AcceptedWithReceipt:
description: Accepted, processing asynchronously headers:
Receipt-Hash: { schema: { type: string } }

3) التوثيق والإذن والنطاقات

OAuth2/OIDC للمستخدمين/الشركاء بيانات اعتماد العملاء/فريق العمل المشترك для S2S.
النطاقات/أدوار الموارد: المدفوعات. «،» كتالوج. «،» مراجعة الحسابات. '.
ReBAC: الوصول «حسب الملكية» (المستأجر/الحساب/الحساب الفرعي).
أسرار JIT: رموز قصيرة العمر، جهاز/شبكة فرعية/منطقة ملزمة.
وضع الجهاز و mTLS للعمليات الهامة (المدفوعات والمفاتيح).

4) الفراغ و «مرة واحدة بالضبط»

Idempotency-Key (رأس) + dedup بواسطة «(مفتاح، حساب، مسار)» على نافذة TTL.
Outbox/CDC لنشر الأحداث - التسليم المضمون.
الآثار مرة واحدة بالضبط: يتم التقاط الآثار الجانبية من خلال مجلة المعاملات ؛ يؤدي التكرار إلى نفس «الاستلام» («الاستلام _ التجزئة»).
سياسات إعادة التجربة: التراجع الأسي، النبضات، النوافذ القصوى.

5) الحدود والحصص وتحديد الأولويات

حدود الأسعار: لكل مفتاح/مستأجر/مسار/منطقة ؛ «ناعم» (429) و «صلب» (قطع).
الحصص/الميزانيات: الحدود القصوى الشهرية/اليومية، الخطابات الشبكية «حصص الوصول».
الاستخدام العادل: أولوية المستأجرين حسب مستوى الخدمة (الذهب/الفضة/البرونز).
عازلات الانفجار: رشقات نارية قصيرة دون تدهور الجيران.

6) التثبيت والفلاتر والعينات

Cursor-based (stable ordering по 'created _ at, id'), 'page _ size' ≤ 1000.
عينات مقطعة إلى شرائح زمنية («من» و «إلى» و «علامة مائية») لسجلات/معاملات.
تصفية DSL: поля المدرجة في القائمة البيضاء، «؟ الحالة =... & المستأجر =... & المنطقة =...».
يشير الاتساق إلى: "لقطة _ at'/" as _ of" للإبلاغ عن واجهات برمجة التطبيقات.

7) الحرث والتوافق

SemVer: "v1"، "v1. 1 '(الامتدادات)، «v2» - فقط على مسارات/مساحات أسماء جديدة.
قواعد التطور: إضافة الحقول/القيم فقط، «نقض → إزالة» من خلال النافذة.
اختبارات التوافق: «العقود كاختبارات» (يحركها المستهلك).

8) الأحداث والخطابات الشبكية والإيصالات

يصف AsyncAPI الموضوعات/الحمولة/التوقيعات.

التسمية التوضيحية: HMAC/EdDSA، الرؤوس «X-Signature»، «X-Nonce»، «X-Timestamp» (نافذة ضيقة)

الإيصالات: «إيصال _ هاش» وتوقيع DSSE على الأحداث الحرجة (المدفوعات، RTP/التغييرات الحدية، قوائم الأسعار).
Retrai and dedup: idempotency with 'idempotency _ key '/' event _ id'.
DLQ/الحجر الصحي: تقارير غير صحيحة/متكررة ذات أسباب.

9) إمكانية الملاحظة والجودة

الآثار: «تتبع _ معرف/امتداد _ معرف» إلزامي من خلال البوابة/الأحداث التجارية/الخطابات الشبكية.
المقاييس: التوافر، p50/p95/p99، معدل الخطأ، معدل إعادة التجربة، التكلفة لكل 1 ألف.
جذوع الأشجار: هيكلية، لا أسرار/معلومات تكنولوجيا المعلومات ؛ 'المستأجر/المنطقة/النسخة' labels.
SLO/التنبيهات: الظروف الموجهة نحو SLO والرونية الآلية (التوقف المؤقت/إعادة المسار/التراجع).

10) الأخطاء ودلالات الحالة

2xx - النجاح (202 للعمليات غير المتزامنة).
4xx - خطأ العميل (422 - التحقق من الصحة، 409 - التضارب/الخصوصية، 429 - الحدود).
5xx - مشاكل مؤقتة.
جسم الخطأ: "رمز"، "رسالة"، "تتبع _ معرف"، "تلميح"، "إعادة تجربة _ بعد ؟ '.
UX للشركاء: جدول «ماذا تفعل» لكل خطأ.

11) السياسات كرمز (OPA/ABAC)

الإذن المركزي: «من/ماذا/أين/متى/لماذا».
السياسات في Git، مراجعة الكود، اختبارات CI (ما قبل الرحلة: "هل ستسمح السياسة ؟ »).
التحقق من SoD: «إنشاء الدفع» ≠ «الموافقة».

12) الأمن والخصوصية والامتثال

تقليل PII: الترميز/الأقنعة، والوصول إلى المرحلة الأولية فقط من خلال اللكمات المعتمدة.
الأسرار: Vault/KMS، TTL قصير، تناوب ؛ حظر الأسرار المشتركة.
التشفير: mTLS/TLS 1. 3، AES-GCM في الاستراحة، HSTS/PKP حسب الاقتضاء.
التوعية بالولاية القضائية - توطين البيانات/المفاتيح لكل منطقة.
سجلات التدقيق: WORM، Merkle-slices، DSSE-signations.

13) العملية: SLI/SLO ولوحات القيادة

• توافر المسار/المنطقة.
• p95 الكمون (اقرأ/اكتب).
• نجاح الخطابات الشبكية (الإيصالات)، تأخر التسليم.
• معدل الخطأ/معدل إعادة التجربة.
• التكلفة لكل 1 ألف طلب وخروج.

SLO (مثال): 99. توافر 95 في المائة ؛ p95 ≤ 120/250 ms ؛ خطوط الويب ≥ 99. 5 في المائة/5 دقائق ؛ P1 MTTR ≤ 60 دقيقة.

14) إدارة التغيير (الإصدارات/التراجع)

أزرق أخضر/كناري للبوابات والطرق الحرجة.
Ficheflags لسلوك عدم الإفراج.
Expand→Migrate→Contract للمخططات والحمولة.
Руны: Rellback Release، Disable Flag، Re-Route، Flush Cache.
القطع الأثرية: الصور/البيانات الموقعة، سجل النسخ.

15) SDK، العملاء، صناديق الرمل

SDKs الرسمية (TS/Java/Python/Go) بنفس الخطأ وإعادة صياغة الدلالات.
بيئات Sandbox مع مفاتيح/شهادات اختبار وأجهزة محاكاة PSP/KYC/مزود المحتوى.
يتم تضمين اختبارات العقد في CI SDK، التوافق الليلي.

16) نموذج البيانات (مبسط)

«api _ key» {id، المستأجر، النطاقات []، tl، created_by}'

"rate _ plan" {مستأجر، quotas{route→cap}، انفجار، أولوية} "

'request _ log' {trace _ id, route, actor, idempotency_key?, status, latency_ms, region, cost_unit}'

'webhook _ recept' {event _ id, endpoint, status, traits, receipt_hash, signation} '

"سياسة" {نسخة، قواعد، توقيع، dsse} "

17) RACI

18) مقاييس الجودة

انجراف العقد: 0 تغييرات «كسر» دون نقض.
معدل الخطأ الفطري: ≤ 0. 01%.
نجاح الويب: ≥ 99. 5٪، تأخر p95 ≤ 60 ثانية.
Auth Fail vs Abuse: حصة الكتل الضارة، الضوضاء ≤ مستوى الهدف.
Cost/1k: المراقبة حسب الطرق والمناطق (الميزانيات/تنبيهات الحد الأقصى).
اعتماد SDK: حصة حركة المرور من خلال SDKs الرسمية.

19) كتب لعب الحوادث

سبايك 429/حدود: رفع سقف الذهب، وخنق المفاتيح «الصاخبة»، والاتصال بشريك.
WebhookLag: زيادة عدد العمال/الدفعات، وتحديد أولويات قوائم الانتظار، وإيقاف تشغيل خطوط الويب الاختيارية مؤقتًا.
PriceMismatch (الكتالوج/FX/Tax): تسوية الإصدار، عجز قوة المخبأ، تراجع القطع الأثرية، التعويض.
انقطاع PSP: تبديل الطريق، والحجر الصحي للمعاملات «الرمادية»، وإعادة التشغيل.
حل وسط لمفتاح واجهة برمجة التطبيقات: الاستدعاء الفوري والتناوب والتدقيق في الأيام 30 الماضية.

20) خصوصية iGaming/fintech

RTP/Limits API: الإصدارات المجمعة والملخصات فقط ؛ التغييرات - مع الإيصالات.
المدفوعات/المدفوعات: 202 + خطوط شبكية موقعة ؛ ترتيب الخصوصية الرئيسية.
الشركات التابعة: إلغاء التحويل، والضمان للمنازعات، والتقارير الموقعة.
اللعب المسؤول: كشف «حواجز الحماية API» للحدود وأحداث RG.

21) قائمة التنفيذ المرجعية

• العقد الموصوف (OpenAPI/AsyncAPI)، التحقق من صحة CI واختبارات المستهلك.
• تم تكوين OAuth2/OIDC والنطاقات وأسرار JIT و mTLS للطرق الحرجة.
• تم إدخال الحماقة والريتراي و DLQ والحجر الصحي.
• الحدود القصوى/الحصص/الأولويات والتنبيهات.
• ترقيم المؤشر، «كـ _ من» عينات متسقة.
• سياسة التحرير والنهب.
• خطوط الويب مع التوقيعات/الإيصالات وإعادة التشغيل والتسريح.
• تتبع/مقاييس/جذوع الأشجار، و SLO والرونية.
• سجلات WORM، وتوقيعات DSSE، وشرائح Merkle.
• SDK، صندوق الرمل، أجهزة المحاكاة، عينات الكود وكيفية القيام بذلك.

22) الأسئلة الشائعة

لماذا 202 للعمليات الطويلة ؟

من أجل عدم الاحتفاظ بالوصلة وتوفير إعادة/إيصال موثوق عبر شبكة الإنترنت.

هل تحتاج إلى كل من OpenAPI و AsyncAPI ؟

نعم: مزامنة الأوامر/الطلبات، async للأحداث/مفاوضات الدولة.

كيف تتجنب كسر التغييرات ؟

قاعدة الإضافة فقط، نقض → لاحظ → إزالة، عقد اختبار العملاء.

أين تخزن الإيصالات ؟

في منطقة دودية ذات توقيعات ؛ يتم إرجاع «receipt _ hash» إلى العميل والتحقق منه عند الطلب.

ملخص: العمليات عبر واجهة برمجة التطبيقات هي نظام العقد والتشغيل: نموذج الوصول الصارم والخصوصية، والحدود والنسخ، وإمكانية الملاحظة و SLO، والتوقيعات والإيصالات. أضف صناديق الرمل و SDKs - وسيتكامل الشركاء بسرعة وأمان وبشكل متوقع، وستتسع الشركات دون فقدان الجودة أو الامتثال.