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

0) مراجعة سريعة (من يفعل ماذا)

• مالك التكامل المخصص
• يتم تحديد الاتصالات عند الطلب (24 × 7/ساعات عمل)
• SLO/SLA المتفق عليه ونافذة دعم الإصدار
• صفحة الحالة وقناة الحوادث (البريد الإلكتروني/slack/webhook)

1) الوصول والبيئات والنسخ

• الوصول إلى الصندوق الرملي/التدريج/الإنتاج
• أكدت نسخة واجهة برمجة التطبيقات: '/v1 '/header 'X-API-Version'
• السماح بتكوين قواعد الملكية الفكرية والشبكة
• الساعة و TZ: جميع الأوقات في التوقيت العالمي المنسق، تزامن NTP
• تم التحقق من توافق SemVer SDK/Client ومصفوفة الإصدار

2) المصادقة والرموز

• الآلية المتفق عليها OAuth2 وثائق تفويض العملاء/رمز أوث + PKCE/API Key/mTLS
• ضبط دوران رمز الوصول مدى الحياة وتحديث الرمز
• لمفتاح واجهة برمجة التطبيقات: يتم عرض السر مرة واحدة، مخزنة في المدير السري
• فحص JWKS/JTI/« طفل »، انحراف الساعة على ± 5 دقائق
• رؤوس «الإذن» غير مسجلة (تنقيح)

bash curl -sS -H "Authorization: Bearer $TOKEN" https://api. example. com/v1/ping

3) الأمن والخصوصية

• TLS 1. 2 +/HSTS، mTLS اختياري
• تقليل PII: نرسل فقط ما نحتاجه، أقنعة في السجلات
• تم توثيق سياسة الاحتفاظ والتصرف (GDPR/DSAR)
• التناوب السري: المفتاح النشط/التالي، خطة التمديد
• مكافحة إساءة الاستخدام: Captcha/Keying Speed/Registration Restructions

4) الحدود والحصص والتراجع

• الرؤوس المعلنة «X-RateLimit- »/« X-Conta-»
• يحترم العميل 429 و 'Retry-After'
• Retrays لـ 5xx/408/429 فقط، التراجع الأسي + jitter
• إعادة المحاولة/تحديد المهلة الزمنية (على سبيل المثال ≤ 5 إعادات، ≤ 60 ج)

5) الفراغ والصراعات

• يتم إرسال جميع عمليات الكتابة باستخدام «Idempotency-Key» (TTL ≥ 24-72 h)
• تكرار النزاع → 409 IDEMP_REPLAY معالجة
• تم تمكين ETag/« If-Match »للتحديثات التنافسية (إذا كانت متاحة)

bash curl -X POST /v1/payments \
-H "Idempotency-Key: pay-<uuid>" \
-d '{"amount":"12. 34","currency":"EUR"}'

6) التثبيت والدلتا الإضافية

• استعداد المؤشر/keyset المستخدم («المؤشر التالي»، «لديه _ أكثر»)
• نوع مستقر «(updated_at، هوية)» موثق
• التحميلات الإضافية: علامة مائية أو رمز التغيير
• التداخل (التداخل 1-2 دقيقة) والتسريح بواسطة '(معرف، نسخة/seq)'

7) تنسيق الخطأ والتشخيص

• نموذج موحد «تطبيق/مشكلة + جسون» (RFC 7807)
• الدعم الميداني: 'خطأ _ رمز'، 'تتبع _ معرف'، 'قابل للاسترجاع'، 'تفصيل'
• وصف خريطة الخطأ وإجراءات العميل (كتيب التشغيل)

json
{
"type":"https://docs. example. com/errors/validation_failed",
"title":"Validation failed",
"status":422,
"error_code":"VAL_001",
"trace_id":"a1b2c3",
"retriable":false
}

8) خطوط الويب: الإقرار والإعادة

• تأكيد النجاح - أي 2xx ؛ FAST ACK بعد الاستفسار
• Подпись HMAC ('X-Signature: sha256 ='...)، 'X-Webhook-Id'،' X-Retry '
• سياسة إعادة التدوير: تراجع + نفض، حتى 24-72 ساعة
• DLQ + إعادة التشغيل: متوفر وتم التحقق من صحته
• التخزين في جهاز الاستقبال، TTL ≥ إعادة تشغيل النوافذ

9) إمكانية الرصد والتعقب

• خطافات OpenTelemetry ممكنة في العميل/SDK
• التتبع على مستوى السلسلة _ id/X-Request-ID
• Дашборды: «الطلبات _ المجموع»، «الأخطاء _ المجموع {الحالة}»، «الكمون _ p95»، «إعادة النظر _ العد»، «429 _ rate»
• أجهزة الإنذار: ارتفاع 5xx/429، ارتفاع p95، انخفاض معدل النجاح، تأخر الويب

promql rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m])

10) الأداء والاستقرار

• برك توصيل، إبقاء على قيد الحياة، HTTP/2/3 حيثما أمكن ذلك
• الضغط الخلفي، طابور العميل ليس «منتفخًا»
• تم تكوين سياسات كسر الدائرة/المهلة/التراجع
• اختبارات التحميل: انفجار 10 ×، وصلات طويلة، وبداية باردة

11) البيانات والعملات والوقت

• الأشكال: ISO-8601 التوقيت العالمي المنسق، المال - السلاسل العشرية/الوحدات الثانوية، لا تعتمد المواقع على البيئة
• الترميزات/اللغات متسقة (على سبيل المثال «Accept-Language» للرسائل ولكن «خطأ _ رمز» للآلة)
• سياسة التقريب/العمولة الموثقة

12) المصالحة

• التسوية اليومية/كل ساعة مع الشيكات
• اختبار واجهة برمجة التطبيقات/التحميلات للتسويات (CSV/JSON، البيانات/التجزئة)
• التناقضات - في التذاكر مع الإشارة إلى 'trace _ id'

13) الامتثال والجوانب القانونية

• شروط الاستخدام المقبولة لواجهة برمجة التطبيقات (الاستخدام العادل/مراقبة الصادرات)
• PII/حاملي البيانات - الأدوار ومجالات التخزين المحددة
• إجراءات الحجز القانوني/سجل التدقيق الممكنة للحوادث

14) بوابة التوثيق والمطور

• OpenAPI/AsyncAPI ذات صلة، وهناك أمثلة على «عجينة النسخ»
• SDK (TS/Py/Java/Go/.NET) - الإصدارات متسقة، كتاب الطبخ متاح
• أعمال الملعب التجريبية، مفاتيح الرمال نشطة
• يمكن رؤية Changelog/التخفيضات/خارطة الطريق في البوابة

15) الاختبار: وظيفي، سلبي، فوضى

وظيفي

• CRUD/سيناريوهات رئيسية مرت (مسار سعيد)
• Pagination/Cursor/Incremental Deltas

سلبي

• 401/403/404/409/422/429/5xx و «Retry-After» process
• توقيع غير صحيح على شبكة الإنترنت، رموز منتهية الصلاحية، أجسام كبيرة

الفوضى

• قم بإسقاط 10-30٪ الأحداث، وإعادة الترتيب، وتأخير 1-10 دقائق
• تعطيل التبعيات (PSP/KYC) → التراجع/الأخطاء الصحيحة

16) القبول والإطلاق (بدء التشغيل)

• تم تمرير Final PRR (مراجعة جاهزية الإنتاج)
• إدراج الكناري: 10٪ → 25٪ → 50٪ → 100٪
• التراجع التلقائي عن إشارات SLO (أخطاء/زمن انتقال/429)
• تم نشر مصفوفة الاتصال بالحوادث ومسار التصعيد
• تراكم CAPA بعد توليد الطيار

17) التشغيل والدعم

• Runbook/playbook: "5xx spike"، "429 storm"، "webhook backlog backlog"، "timeout'
• تقارير الميزانية العادية للمكتب الإقليمي/الخطأ
• تدوير الأسرار والمفاتيح في جدول زمني
• تمت الموافقة على خطة التخفيضات/الهجرة (تاريخ انتهاء الصلاحية)

18) أنماط القطع الأثرية

قالب Env-config

yaml api:
base_url: https://api. example. com/v1 timeout_ms: 10000 retries: { max: 5, strategy: expo-jitter }
auth:
kind: oauth2 token_url: https://auth. example. com/oauth2/token scopes: [wallet:read, wallet:write]
webhooks:
secret_ref: secret/webhook-hmac parallelism: 10 max_body_kb: 256

سياسة إعادة التدوير (زائفة)

json
{"initial":1,"max":60,"factor":2. 0,"jitter":0. 2,"retriable":["5xx","408","429"]}

19) القائمة المرجعية النهائية «للتوقيع»

• البيئات/الإصدارات/المفاتيح/allowist جاهزة
• تم تكوين واختبار Auth/JWT/keys/mTLS
• تنفيذ الحدود/الحصص/إعادة التصنيف/الخصوصية
• أعمال التثبيت/المؤشر/الدلتا بشأن البيانات
• خطافات الويب: التوقيعات، الإعادة، DLQ/إعادة التشغيل تم التحقق منها
• الأخطاء «مشكلة + جسون»، «تتبع _ معرف» على جميع جذوع الأشجار
• لوحات المعلومات/التنبيهات التي تم جمعها، تم تمكين OTEL
• اجتازت اختبارات الحمل/السلبية/الفوضى
• تتلاقى التسويات والتقارير، ويتم إضفاء الطابع الرسمي على الدفاتر الجدولية
• PRR/canary/خطة التراجع جاهزة، تم الإشارة إلى جهات الاتصال عند الطلب

المجموع

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