سياسة الإصدارات
إصدار الـ API هو الجزء الأول من كل مسار: /v1.
ما يمكن أن يتغير في v1
هذه التغييرات قد تُضاف إلى v1 في أي وقت، وكل منها يُذكر في سجل التغييرات:
- Endpoints وموارد جديدة، بصلاحياتها الخاصة؛
- حقول و Query Parameters اختيارية جديدة في الطلبات؛
- حقول جديدة في الردود؛
- أكواد أخطاء جديدة؛
- قيم جديدة في الحقول التي تحدد نوعاً أو قناة، مثل
createdVia.
لذلك يجب أن يتجاهل الكود عندك أي حقل لا يعرفه في الرد، وأن يتعامل مع أي قيمة لا يعرفها، مثل أن يعامل قيمة غير معروفة في createdVia كأنها unknown.
ما لا يتغير في v1
- الحقل الموجود يحتفظ باسمه ونوعه ومعناه.
- كود الخطأ يحتفظ بمعناه. اعتمد على
code، أماmessageفنص موجّه للمستخدم وقد تتغير صياغته أو ترجمته في أي وقت. - الطلب الذي يعمل اليوم يبقى يعمل.
ويبقى التحقق من الطلبات صارماً: أي حقل أو Query Parameter لا يعرفه الـ Endpoint يُرفض بـ 400 unknown_parameter. والحقل الاختياري الجديد لا يُقبل إلا بعد إطلاقه وذكره في سجل التغييرات.
التغيير الذي يكسر التوافق
التغيير الذي يوقف عميلاً يعمل، مثل حذف حقل أو تغيير اسمه، يأتي في إصدار جديد بمسار خاص به، مثل /v2.