الإصدارات وإيقاف الدعم

كل نقطة نهاية تعيش تحت /api/v1. هذه الصفحة هي السياسة كاملة: ما الذي تلتزم /api/v1 بعدم فعله أبدًا، وما الذي يُعدّ تغييرًا جذريًا (breaking)، وكيف تُوقَف عملية بعينها عن الدعم دون كسر أي عميل ما يزال يستدعيها، وسجلّ كل تصحيح على مستوى العقد قمنا به.

ثبات /api/v1#

داخل /api/v1 نُجري تغييرات إضافية فقط:

• نقطة نهاية جديدة.
• حقل اختياري جديد في الطلب.
• حقل جديد في الاستجابة.
• رمز خطأ (code) جديد ومنفصل لحالة فشل جديدة فعلًا.

لا نفعل أبدًا داخل /api/v1:

• حذف حقل من استجابة.
• تضييق نوع حقل (مثال: تحويل حقل قابل لأن يكون null إلى غير قابل لذلك أمر مقبول؛ العكس — أو توسيع string إلى string | number — غير مقبول).
• إضافة حقل إلزامي جديد في الطلب.
• تغيير رمز حالة HTTP الذي تُعيده عملية لنتيجة معيّنة.
• تغيير error.code الذي تُعيده حالة فشل موجودة أصلًا.

إن كان تكاملك يقرأ فقط الحقول التي يعرفها ويتحمّل ظهور حقول جديدة، فسيستمر بالعمل على /api/v1 إلى أجل غير مسمّى — هذا هو جوهر القاعدة.

ما الذي يُعدّ تغييرًا جذريًا (breaking)#

أي شيء في قائمة "لا نفعل أبدًا" أعلاه هو تغيير جذري، ولا يُطبَّق أبدًا داخل /api/v1. التغيير الجذري يعني بدلًا من ذلك /api/v2، مُعلَنًا عنه قبل 180 يومًا على الأقل من بدء إيقاف دعم /api/v1. يعمل الإصداران معًا جنبًا إلى جنب طوال فترة الإشعار كاملة — لا يُسحَب شيء من تحت قدَمَي أي مُكامِل دون تحذير.

إيقاف دعم عملية بعينها#

يمكن إيقاف دعم عملية واحدة داخل /api/v1 — تبقى تعمل بالكامل، لكنها تُعلَّم للإزالة لاحقًا (عادةً لأن /api/v2 أو عملية أحدث تحلّ محلّها). طوال ما تبقّى من عمرها تحمل ثلاثة ترويسات و "deprecated": true في مستند OpenAPI:

HTTP/1.1 200 OK
Deprecation: @1735689600
Sunset: Wed, 01 Jul 2026 00:00:00 GMT
Link: <https://docs.institflow.com/en/guides/versioning#deprecations>; rel="deprecation"

• Deprecation — متى بدأ إيقاف الدعم، بصيغة @ متبوعة بثوانٍ يونكس (RFC 9745). المثال أعلاه، @1735689600، هو 2025-01-01T00:00:00Z.
• Sunset — أقرب تاريخ يمكن فيه إزالة العملية، بصيغة IMF-fixdate (RFC 8594)، ويكون دائمًا بعد Deprecation بـ 180 يومًا على الأقل.
• Link — يشير إلى جدول إيقافات الدعم أسفل هذه الصفحة، بحيث يجد أي عميل يكتفي بتسجيل الترويسات طريقةً لمعرفة السبب.

replacedBy، عند وجود بديل مباشر، وملاحظة قصيرة قابلة للقراءة note، تظهران في الجدول أدناه وفي مرجع API المُولَّد لتلك العملية — لا في الترويسات نفسها، التي تبقى صغيرة وقابلة للتحليل الآلي.

ترويسات حدود معدّل الطلبات#

كل استجابة — سواء كانت لعملية مُوقَفة أم لا، ناجحة أم لا — تحمل RateLimit-Limit وRateLimit-Remaining وRateLimit-Reset. وكل استجابة 429 RATE_LIMITED — سواء من المُحدِّد العام لكل عنوان IP/مستخدم الذي يحمي كل مسار، أو من ميزانية مفتاح API السرّي الخاصة به — تحمل إضافةً إلى ذلك Retry-After، بالثواني، لكي يعرف العميل الملتزم بالضبط كم ينتظر دون تخمين من RateLimit-Reset وحدها.

سجلّ التغييرات#

تصحيحات على مستوى العقد وحالات إيقاف الدعم، الأحدث أولًا.