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

> ما الذي يمكن أن يتغير في v1 دون إشعار، وما الذي لا يتغير أبداً، وكيف يأتي التغيير الذي يكسر التوافق.

إصدار الـ API هو الجزء الأول من كل مسار: `/v1`.

## ما يمكن أن يتغير في v1

هذه التغييرات قد تُضاف إلى v1 في أي وقت، وكل منها يُذكر في [سجل التغييرات](https://docs.kosoor.com.sa/ar/changelog.md):

- Endpoints وموارد جديدة، بصلاحياتها الخاصة؛
- حقول و Query Parameters اختيارية جديدة في الطلبات؛
- حقول جديدة في الردود؛
- أكواد أخطاء جديدة؛
- قيم جديدة في الحقول التي تحدد نوعاً أو قناة، مثل `createdVia`.

لذلك يجب أن يتجاهل الكود عندك أي حقل لا يعرفه في الرد، وأن يتعامل مع أي قيمة لا يعرفها، مثل أن يعامل قيمة غير معروفة في `createdVia` كأنها `unknown`.

## ما لا يتغير في v1

- الحقل الموجود يحتفظ باسمه ونوعه ومعناه.
- كود الخطأ يحتفظ بمعناه. اعتمد على `code`، أما `message` فنص موجّه للمستخدم وقد تتغير صياغته أو ترجمته في أي وقت.
- الطلب الذي يعمل اليوم يبقى يعمل.

ويبقى التحقق من الطلبات صارماً: أي حقل أو Query Parameter لا يعرفه الـ Endpoint يُرفض بـ `400 unknown_parameter`. والحقل الاختياري الجديد لا يُقبل إلا بعد إطلاقه وذكره في سجل التغييرات.

## التغيير الذي يكسر التوافق

التغيير الذي يوقف عميلاً يعمل، مثل حذف حقل أو تغيير اسمه، يأتي في إصدار جديد بمسار خاص به، مثل `/v2`.

المصدر: https://docs.kosoor.com.sa/ar/versioning