واجهة برمجة التطبيقات للنظام البيئي

(القسم: النظام الإيكولوجي والشبكة)

1) الأهداف والمبادئ

• التكامل السريع الذي يمكن التنبؤ به (↓ من وقت إلى اندماج).
• الموثوقية وقابلية التوسع (SLO، QoS، الضغط الخلفي).
• السلامة والامتثال (الحقوق الدنيا، مراجعة الحسابات).
• التطور بدون أعطال (الإصدارات، التوافق، ficheflags).

المبادئ: العقد أولاً، تقليل البيانات، الخصوصية، القابلية للرصد افتراضيًا، «سرعتان» من الإطلاقات (الأساسية مقابل التجريبية).

2) تصنيف واجهة برمجة التطبيقات

1. REST/HTTP - عمليات CRUD/القيادة المتزامنة، مفتاح الخصوصية، التثبيت/المؤشرات.
2. gRPC/QUIC - زمن انتقال منخفض، تيارات، بروتوكولات ثنائية.
3. Events (Pub/Sub) - domain events ('deposit. '،' دفع تعويضات. «،» الجسر. «،» المخاطرة. ').
4. خطوط الويب - الإشعارات العكسية بالتوقيعات وإعادة التدوين.
5. GraphQL (محدود) - يقرأ التجميع على واجهات المتاجر المجسدة.
6. Admin/Meta - الأدلة والإصدارات والحالات والمفاتيح والحصص.

مستويات الوصول: عامة (طرق/قراءة محدودة)، شريك (نطاقات وحصص)، داخلية (ملامح خاصة).

3) العقود والمخططات

OpenAPI/AsyncAPI/Protobuf IDL هو مصدر واحد للحقيقة.
عقود البيانات - اختبارات التوافق، وصفات الدوائر، وحظر «كسر» الحقول بدون MAJOR.
الكتالوجات: الأصول/الشبكات، PSP/الأساليب، المناطق/الولايات القضائية، إصدارات SDK، أعلام القدرات.

عقد REST الأدنى (جزء OpenAPI)

yaml openapi: 3. 0. 3 info: { title: Ecosystem Core API, version: "2. 6. 0" }
paths:
/v2/payouts:
post:
operationId: createPayout parameters:
- in: header name: Idempotency-Key required: true schema: { type: string, maxLength: 64 }
requestBody:
required: true content:
application/json:
schema:
$ref: "#/components/schemas/PayoutRequest"
responses:
"202": { $ref: "#/components/responses/Ack" }
"409": { description: "Duplicate (idempotent)" }
components:
schemas:
PayoutRequest:
type: object required: [amount, currency, destination]
properties:
amount:  { type: string, pattern: "^[0-9]+(\\.[0-9]{1,9})?$" }
currency: { type: string, example: "USD" }
destination: { type: string }
metadata: { type: object, additionalProperties: true }

الأحداث (AsyncAPI)

yaml asyncapi: 2. 6. 0 info: { title: Ecosystem Events, version: "1. 9. 0" }
channels:
payout. finalized:
subscribe:
message:
name: PayoutFinalized payload:
type: object required: [id, ts, amount, currency, status, signature]
properties:
id: { type: string }
ts: { type: string, format: date-time }
amount: { type: string }
currency: { type: string }
status: { type: string, enum: ["finalized","failed"] }
signature: {type: string} # source signature

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

SemVer: 'MAJOR. قاصر. PATCH '. MINOR/PATCH - متوافقة مع الخلف ؛ MAJOR - الإصدارات المتوازية ('/v1 '، '/v2') + المحولات.
سياسة الرفض: نافذة ≥ 90 يومًا، «سطرين» للدعم، إخطارات تلقائية للعقود.
أعلام الميزة: حقول/طرق تمكين/تعطيل حسب المنطقة/الشريك.
التفاوض على القدرات: الإعلان عن الملفات الشخصية المدعومة عند المصافحة.

5) الفراغ والأوامر والمؤشرات

Idempotency-Key for commords (creation/ancel), TTL keys ≥ 72 ساعة.
دلالات مرة واحدة بالضبط عبر outbox/inbox والمستهلك الغبي.
التثبيت بالمؤشرات: «المؤشر التالي»، مقاومة الإدخال/الحذف.
الفرز والفلاتر مستقرة وموثقة بوضوح.

6) الأمن والثقة

mTLS (service↔service)، تثبيت السيرتات وتدوير المفاتيح.
OAuth2/OIDC (وثائق اعتماد العملاء، JWT مع TTL قصير)، PoP/DPoP للربط مع القناة.
التوقيعات الشبكية (NMAS/key version/time)، حماية التكرار.
RBAC/ABAC and POLP: scopes, org_id/tenant_id, limits on object/operation.
تقليل DLP/PII: حظر PII في الملصقات/السجلات، ترميز المعرفات.
حدود الأسعار و WAF: لكل منظمة/مسار/منطقة، الحماية من سوء المعاملة.

عينة السياسة الرئيسية (YAML)

yaml auth:
oauth2:
issuer: "https://auth. ecosys"
jwks_uri: "https://auth. ecosys/.well-known/jwks. json"
token_ttl_s: 900 mtls:
required_for: ["internal","partner_p0"]
scopes:
- name: payouts:write
- name: payouts:read
- name: events:subscribe

7) الحصص و QoS والضغط الخلفي

فئات QoS: P0 (المدفوعات/الجسر/الانتهاء)، P1 (المنتج)، P2 (السائب/الأرشيف).
الحصص/الحدود: RPS، طلبات الموافقة، bytes/sec، الموضوع/الطرف للأحداث.
مراقبة القبول: الرفض المبكر للطلبات «باهظة الثمن»، وحراسة الاستعلام الثقيل.
الضغط الخلفي: الرموز/الاعتمادات، قوائم الانتظار مع DLQ، تعيد الدرج مع النفاخ.

سياسة الحصص

yaml quotas:
partner_default:
rps: 200 concurrent: 100 webhooks_outbound_rps: 50 p0:
rps: 100 p95_latency_ms: 400

8) إمكانية الرصد: SLI/SLO، المقاييس، الآثار

• p95/99 latency по маршрутам, Success Rate, Error build burn, Queue-lag p95, Freshness webooks, Delivery success%.
• نسبة الامتثال للعقود (المخططات/التوقيعات).
• إعادة تشغيل Webhook/انخفض٪.

SLO: P0 p95 ≤ 400 mm، التوافر ≥ 99. 95%; تسليم الويب p95 ≤ 2 с ؛ نضارة الأحداث p95 ≤ 60 с.

المقاييس: مخططات الكمون، رموز الخطأ، حجم الردود، RPS، لكل مستأجر.
الآثار: من طرف إلى طرف 'trace _ id' (edge→gateway→service→DB→event/webhook).
جذوع الأشجار: هيكلية، بدون مؤشر الاستثمار الدولي، ترتبط بـ 'طلب _ معرف'.

9) أنماط الإطلاق الخالية من التوقف

أزرق أخضر/كناري مع بوابات SLO وطرد خارجي.
تطور المخطط أولاً: إضافة الحقول فقط، محولات للعملاء القدامى.
هجرات قاعدة البيانات بدون توقف: DDL عبر الإنترنت، محولات ثنائية الاتجاه.
مراقبة التغيير: سجل التوقيت ومراجعة الحسابات والتوافق.

10) الفهارس والسجلات

واجهة برمجة التطبيقات/سجل الإصدار

sql
CREATE TABLE api_registry(
name TEXT, kind TEXT,      -- rest    grpc    events    webhook version TEXT, status TEXT,   -- active    canary    deprecated    retired slo JSONB, owner TEXT,
PRIMARY KEY (name, version)
);

فهرس الأحداث

sql
CREATE TABLE event_catalog(
topic TEXT PRIMARY KEY,
schema_version TEXT,
qos TEXT,
retention_days INT,
pii BOOLEAN DEFAULT false
);

المفاتيح/النطاقات

sql
CREATE TABLE api_keys(
key_id TEXT PRIMARY KEY,
org_id TEXT, scopes TEXT[], status TEXT, expires_at TIMESTAMPTZ
);

11) الاختبار والامتثال للعقود

اختبارات العقد: توليد العملاء، التحقق من صحة المخطط، negative-_cases.
اختبارات حدث إعادة التشغيل: مقاومة التكرار/إعادة الترتيب.
الفوضى/اختبارات اللات: حقن فقدان/نفث، وقاية بطيئة.
الاختبارات الأمنية: توقيعات شبكات الويب، تناوب المفاتيح، هجمات إعادة التشغيل.
ملامح الأداء: مسامير SLA، الطرق الساخنة، جسر DA/التبعية.

12) أمثلة على الوصلات البينية

خطوط الويب (توقيع وعودة)

yaml webhooks:
deliveries:
retry:
attempts: 5 backoff_ms: [200, 800, 1600, 3200, 6400]
jitter: true signature:
alg: "HMAC-SHA256"
header: "X-ECO-Signature"
timestamp_header: "X-ECO-Timestamp"
tolerance_s: 300

الرسم البياني QL (التجميع يقرأ، اقرأ فقط)

graphql type Query {
payouts(status: [Status!], first: Int!, after: String): PayoutConnection!
}

gRPC (تدفق الحدث)

proto service EventStream {
rpc Subscribe(SubscribeRequest) returns (stream Event);
}

13) العمليات والأدوار

مالك واجهة برمجة التطبيقات - العقد/الإصدار/SLO/الحصة.
الأمن - المفاتيح/التوقيعات/مراجعة الحسابات/DLP.
SRE/Ops - لوحات القيادة، التنبيهات، السعة.
نجاح الشريك - الصعود، الحدود، phicheflags.
الامتثال - الولايات القضائية والجزاءات والإبلاغ.

14) لوحات القيادة

واجهة برمجة التطبيقات الأساسية: الكمون/الخطأ/RPS حسب المسار والخيمة.
خطافات الويب: التسليم p95، الإعادات، القطرات، التوقيعات.
الأحداث: النضارة، التأخر، صحة المستهلك، DLQ.
الأمن: مفاتيح انتهاء الصلاحية، التوقيعات، الطلبات المرفوضة.
الإدارة: الإصدارات/الاستنكافات النشطة، توافق العقود.

15) حوادث قواعد اللعبة

ألف - نمو فترة الكمون P95

1. تمكين P0 والأولوية P2-throttle ؛ 2) بوابات المقياس ؛

2. قم بتبديل جزء من القراءات إلى ذاكرة التخزين المؤقت 4) تحليل الطرق «الساخنة».

باء - إسقاط شبكة التوصيل

1. التحقق من التوقيعات/مناوبة الساعة، 2) زيادة عمليات إعادة/مهلات الإغلاق،

2. قم بتشغيل الدفعات، 4) التبديل مؤقتًا إلى نقطة نهاية الرصاصة.

جيم - عقود الانجراف

1. مكّن «وضع صارم»،

2. إخطار المنتج، 3) تحرير المحول، 4) بعد الوفاة، تحديث البطانات.

دال - الحل التوفيقي المتعلق بالمفتاح/الشهادة

1. الإلغاء/التناوب، 2) إعادة تشغيل خطوط الويب، 3) مراجعة الحسابات، 4) إخطار الشركاء.

هاء - تكرار/خذ الانفجار

1. تحقق من Idempotency-Key/TTL، 2) تقوية الوفاة، 3) الحد من المصدر «الصاخب».

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

1. وصف العقود (OpenAPI/AsyncAPI/IDL)، بما في ذلك البطانات و CI.
2. ضبط auth (OAuth2/OIDC, mTLS), webhook signations, key duration.
3. أدخل الحصص/QoS/الحدود، وحراسة الاستعلام الثقيلة والضغط الخلفي.
4. زيادة إمكانية الملاحظة: SLI/SLO، المسارات، لوحات القيادة، التنبيهات.
5. تنظيم الإصدارات: كناري/أزرق أخضر، هجرات المخطط أولاً.
6. بدء الإصدار/الحدث/دليل المفتاح واستنفاد العمليات.
7. إجراء فوضى/اختبارات perf/security، وترتيب كتب اللعب.
8. تجديد البيانات بانتظام والامتثال التنظيمي.

17) مسرد

العقد أولاً - تصميم واجهة برمجة التطبيقات من خلال عقود رسمية للترميز.
Idempotency-Key - مفتاح يجعل العملية تتكرر بأمان.
AsyncAPI - مواصفات واجهات الحدث.
QoS - جودة الخدمة/فئة الأولوية.
DLQ - «قائمة انتظار ميتة» لرسائل المشكلة.
حرق ميزانية الخطأ - معدل «حرق» ميزانية الخطأ بالنسبة إلى SLO.

خلاصة القول: إن واجهة برمجة التطبيقات للنظام البيئي ليست مجموعة من نقاط النهاية، ولكنها نظام مُدار للعقود والأمن والحصص وقابلية الملاحظة. من خلال اتباع هذا الإطار، يكتسب النظام البيئي تكاملات سريعة، و SLOs يمكن التنبؤ بها، والتطور الآمن دون توقف - من طبقة الشبكة والمصادقة إلى تدفقات الأحداث والإبلاغ.