استراتيجية API

#النمط

REST JSON تحت /api/v1 للعمليات الأساسية، WebSocket للأحداث الفورية، وOpenAPI 3.1/AsyncAPI كمصدر عقد قابل للاختبار.

#المعايير

• أخطاء موحدة: code، message، details، request_id.
• cursor pagination للـ feeds/messages والتعليقات الكبيرة.
• ISO-8601 UTC، locale وRTL شأن عرض لا تغيير بيانات.
• idempotency keys للعمليات القابلة للتكرار أو الحساسة.
• versioning وdeprecation معلنان ودعم حد أدنى لإصدارات التطبيقات.

#المصادقة والصلاحيات

Tokens قصيرة العمر وتجديد/إبطال وإدارة أجهزة؛ كل مورد يخضع لـ authorization على الخادم. RBAC للإدارة والمؤسسات، وسياسات resource-level للمحتوى والمحادثات.

#الحماية والتشغيل

Rate limits حسب العملية/المستخدم/IP، request IDs، structured logs، metrics لكل endpoint، quotas وtimeouts للintegrations. لا تُرسل أسرار أو PII غير ضرورية.

#دورة التغيير

Design review → contract/mock → implementation → contract/security tests → changelog → staged release. أي تغيير كاسر ينتقل لإصدار جديد مع فترة دعم معلنة.