# استراتيجية 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. أي تغيير كاسر ينتقل لإصدار جديد مع فترة دعم معلنة.