سياسة الإصدارات

تبني على K-Agent مرة واحدة ويستمر عملك. إصدار الواجهة البرمجية جزء من المسار، /v1، و**/v1 لا يتغير إلا بالإضافة**.

ما الذي قد يتغير داخل /v1

هذه تغييرات إضافية قد تصدر في أي وقت، دون إشعار سوى سجل التغييرات:

• نقاط نهاية جديدة؛
• حقول ومعاملات اختيارية جديدة في الطلبات؛
• حقول جديدة في الاستجابات وفي بيانات الأحداث؛
• قيم جديدة في القوائم المفتوحة (مثل outcome أو reason_type أو channel جديد)؛
• أنواع أحداث جديدة في البث والويب هوك؛
• رموز أخطاء وتحذيرات جديدة.

وهذه لن تحدث داخل /v1: حذف نقطة نهاية أو حقل أو تغيير اسمه، أو تغيير نوع الحقل أو معناه، أو جعل حقل اختياري إلزاميًا، أو تغيير رمز خطأ تتلقاه بالفعل. فمثل هذه التغييرات تأتي مع إصدار رئيسي جديد يُعلن عنه قبل وقت كافٍ.

اكتب عملاء متسامحين

• تجاهل الحقول التي لا تعرفها. لا تفشل حين تحمل استجابة أو حدث حقولًا أكثر مما تتوقع.
• تعامل مع قيم القوائم غير المعروفة. عامل outcome أو status غير معروف بقيمة افتراضية معقولة بدل الانهيار. وفي عقد OpenAPI تُعرَّف القوائم المفتوحة بالنوع type: string مع قائمة x-enum-values بقيم اليوم.
• تجاهل أنواع الأحداث غير المعروفة في البث والويب هوك.
• ابنِ على code الخاص بالخطأ وحالة HTTP، لا على message المقروءة، فهي مترجمة وقد تُعاد صياغتها.

ترويسة K-Agent-Version

ثبّت السلوك الذي كُتب عليه تكاملك بترويسة مؤرخة:

K-Agent-Version: 2026-10-06

• 2026-10-06 هو الإصدار الحالي — والأول. والطلب دون الترويسة يستخدمه.
• القيمة التي ترسلها تُعاد في كل استجابة.
• القيمة غير المعروفة تعيد 400 invalid_api_version.
• الإصدارات المؤرخة هي الطريقة التي سنقدّم بها أي تغيير في السلوك لا يكون إضافيًا خالصًا، دون كسر العملاء الذين ثبّتوا تاريخًا أقدم.

الإيقاف والإنهاء

إذا أُوقفت نقطة نهاية أو حقل يومًا ما، فستحمل الاستجابات التي تستخدمه الترويسة القياسية Deprecation وترويسة Sunset بتاريخ توقفه عن العمل، وسيوضح سجل التغييرات البديل. هذه الترويسات محجوزة اليوم: لا شيء في /v1 موقوف.

العقد

العقد القابل للقراءة آليًا هو وثيقة OpenAPI 3.1 على /docs/openapi.yaml، وتقدّمها الواجهة البرمجية أيضًا على /openapi.json. وتتحقق اختباراتنا من تطابق كل مسار يسجله الخادم معها، فيصف مرجع الواجهة البرمجية دائمًا ما يفعله الخادم فعلًا.