الإصدارات والتوافق

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

رقم الإصدار

لواجهة API رقم إصدار مثل 1.62.0، يتغيّر مع كل إطلاق:

الرقم الثانوي حين يُضاف شيء: نقطة نهاية، أو حقل، أو حدث؛
رقم التصحيح حين يُصحَّح وصف أو نص رسالة ولا يتغيّر شيء آخر.

يمكنك في أي وقت قراءة الإصدار الذي يخدمه العنوان:

أين	ماذا
`GET /openapi.json`	الحقل `info.version` في المواصفة
كل حدث في سجل الأحداث وكل تسليم لخطاف ويب	الحقل `api_version`، أي الإصدار الذي يتبع `data` مخططه

وللعملية GET /v1/health أيضًا الحقل version، لكنه إصدار Sursa الذي يخدم العنوان، لا إصدار واجهة API.

لا تختار الإصدار الثانوي: كل طلب يخدمه الإصدار الحالي. وبفضل القواعد أدناه، هذا آمن.

ما يمكن أن يتغيّر في /v1

قد تأتي هذه التغييرات في أي إصدار ثانوي. اكتب تكاملك بحيث لا تكسره:

نقاط نهاية جديدة.
معاملات وحقول طلب جديدة اختيارية. والطلبات التي لا تتضمنها تعمل كما من قبل.
حقول جديدة في الاستجابات والكائنات والأحداث.
قيم تعداد جديدة في الاستجابات، مثل حالة جديدة للبطاقة أو نوع حدث جديد.
رموز أخطاء جديدة، وترويسات استجابة جديدة.
حدود تصبح أقل صرامة: طول أقصى أكبر، أو مدى أوسع.
إعادة صياغة نصوص message في الأخطاء وإعادة صياغة الأوصاف.

ما يجب أن تتحمّله شيفرتك

تجاهل الحقول التي لا تعرفها. لا تفشل حين تحتوي الاستجابة حقولًا أكثر مما تتوقع، ولا تستخدم مخططات صارمة ترفضها.
اقبل قيم التعداد التي لا تعرفها. كل تعداد في الاستجابة قابل للنمو. تعامل مع القيمة المجهولة على أنها «أخرى» لا على أنها خطأ.
تجاهل أنواع الأحداث التي لا تعرفها، في خطافات الويب وفي التدفقات على السواء.
تعامل مع رموز الأخطاء المجهولة حسب حالة HTTP: انظر الأخطاء.
لا تعتمد على ترتيب الحقول في كائنات JSON، ولا على النص الحرفي للرسائل.

ما لا يتغيّر أبدًا في /v1

لا تُغيَّر أبدًا تسمية مسار أو معامل أو حقل أو قيمة تعداد، ولا يُحذف أي منها.
لا يتغيّر نوع الحقل أبدًا، ولا يكتسب حقل معنى جديدًا، مثل وحدات جديدة.
الطلب المقبول اليوم لا يُرفض لاحقًا.
رمز حالة الاستجابة الناجحة يبقى كما هو.
تحتفظ رموز الأخطاء بمعناها، ويحتفظ الحقل detail في استجابات الأخطاء بشكله.
لا تُغيَّر أبدًا تسمية أنواع الأحداث ولا تُحذف، والحقل data فيها لا يتغيّر إلا بإضافة حقول.

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

إذا احتجنا يومًا إلى تغيير غير متوافق، فسيصدر في إصدار رئيسي جديد، مثل /v2، إلى جانب /v1. ويبقى /v1 عاملًا دون تغيير، ويعمل الإصداران جنبًا إلى جنب.

حين يتقرر إيقاف مسار:

يُعلَّم بالقيمة deprecated في المواصفة، ويُدرَج في سجل التغييرات مع تاريخ إيقافه.
تحمل استجاباته الترويستين Deprecation: true وSunset: <date>.
يبقى عاملًا مدة 180 يومًا على الأقل بعد الإعلان. وتُبلَّغ كتابيًا المؤسسات التي تستخدمه مفاتيحُ API الخاصة بها، قبل 90 يومًا على الأقل.
بعد تاريخ الإيقاف، يجيب بالحالة 410 مع الرمز api.gone لمدة 90 يومًا أخرى.

راقب الترويسة Deprecation في سجلاتك أو في المراقبة: إنها أول إشارة إلى أن مسارًا تستخدمه في طريقه إلى الإيقاف.

البقاء على اطلاع

يسرد سجل التغييرات في هذه البوابة كل إصدار مع ما أُضيف وما أُهمل. وقبل أن تحدّث تكاملك، قارن شيفرته بالإدخالات منذ الإصدار الذي بنيته عليه.