كل واجهة برمجية تبدأ كوعد. بمجرد أن يعتمد تطبيق جوال أو تكامل مع شريك أو سكربت لدى عميل على شكل استجاباتك، يصبح هذا الشكل ملكاً لهم بقدر ما هو ملك لك. غيّر اسم حقل واحد وسيبدأ تطبيق صدر قبل ستة أشهر بالتعطل على هواتف لا يمكنك تحديثها.
ومع ذلك يجب أن تتغير الواجهات. المنتجات تتطور، ونماذج البيانات تُنظَّف، ومتطلبات الأمان تتشدد. الفرق التي تتعامل مع هذا جيداً لا تتجنب التغيير. إنها تعامل الإصدارات كقرار منتج له سياسة وعملية ومسؤول، لا كبادئة في الرابط تُضاف في اللحظة الأخيرة.
في هذا الدليل ستتعرف على:
- كيف تقارن عملياً بين الإصدار في الرابط وفي الترويسة وبالتاريخ
- أي التغييرات آمنة بدون إصدار جديد
- كيف تشغّل الإصدارات وتعلن إيقافها وتنهيها دون مفاجآت
نبني واجهات برمجية للويب والجوال والشركاء كل أسبوع، والدروس نفسها تتكرر.
جدول المحتويات
1. لماذا يهم تحديد إصدارات واجهات API
يمكن إعادة نشر عميل ويب في دقائق، أما تطبيق الجوال فلا. يبقى المستخدمون على إصدارات قديمة لشهور، وبعضهم لا يحدّث أبداً. لذلك تخدم كل واجهة عامة ذيلاً طويلاً من إصدارات العملاء في آن واحد، وأقدمها يحدد الحد الأدنى الفعلي للتوافق.
تزداد المخاطر مع تكاملات الشركاء. دورة إصدارهم ليست دورتك، والتغيير الكاسر عندك يصبح انقطاعاً عندهم، يتبعه تصعيد إلى فريق الدعم لديك.
يمنحك الإصدار حدوداً واضحة للعقد: هذا السلوك مجمّد، والسلوك الجديد هناك. بدونه يصبح كل تغيير مجازفة، فتلجأ الفرق إلى تجميد الواجهة بالكامل، وهذا يبطئ المنتج بطريقة أخرى.
مثال توضيحي
2. اختيار أسلوب الإصدارات
لا يوجد أسلوب صحيح للجميع، بل الأسلوب المناسب لعملائك وفريقك. هذه الأساليب الثلاثة الأكثر شيوعاً.
| الأسلوب | مثال | الميزة | العيب |
|---|---|---|---|
| مسار الرابط | /v2/orders |
واضح وسهل التوجيه والتخزين المؤقت | الإصدار ينطبق على الواجهة كلها |
| الترويسة أو نوع الوسائط | Accept: application/vnd.app.v2+json |
روابط نظيفة وتحكم لكل مورد | أصعب في الاختبار اليدوي وتتبع الأخطاء |
| بالتاريخ | API-Version: 2026-03-01 |
دقيق وبلا إصدارات ضخمة | يحتاج أدوات لإدارة التحويلات |
2.1 الإصدار في مسار الرابط
هذا هو الخيار الافتراضي لأغلب الفرق، ولسبب وجيه. يظهر في السجلات، ويسهل توثيقه، وتوجّهه البوابات وشبكات التوصيل بسهولة. الثمن هو الدقة: الانتقال إلى v2 من أجل نقطة نهاية واحدة يغريك بنسخ كل ما عداها.
2.2 الإصدار بالترويسة وبالتاريخ
تُبقي الترويسات الروابط ثابتة وتسمح لكل مورد بالتطور وحده. أما الإصدار بالتاريخ فيذهب أبعد: يُثبَّت كل عميل على تاريخ تكامله، وتُطبَّق التغييرات كتحويلات صغيرة فوقه. إنه قوي لكنه يتطلب استثماراً في أدوات داخلية.
نصيحة: إذا كان عملاؤك في الغالب تطبيقات جوال أو أطرافاً خارجية لا يمكنك التنسيق معها، فاختر أبسط أسلوب يستطيع فريقك تطبيقه باستمرار. إصدار بسيط في الرابط يُطبَّق بصرامة أفضل من أسلوب ذكي منفّذ جزئياً.
3. تصميم تغييرات لا تكسر العملاء
أفضل إصدار هو الذي لا تحتاج إلى إصداره. يمكن شحن أغلب التغييرات بشكل إضافي إذا صممت لذلك.
3.1 تغييرات آمنة
- إضافة حقل اختياري جديد في الاستجابة
- إضافة نقطة نهاية جديدة
- إضافة معامل اختياري في الطلب بقيمة افتراضية معقولة
- إضافة قيمة جديدة لقائمة قيم محددة، إذا أُبلغ العملاء بتحمّل القيم غير المعروفة
3.2 تغييرات كاسرة
- حذف حقل أو تغيير اسمه
- تغيير نوع الحقل أو معناه، حتى بشكل طفيف
- جعل معامل اختياري إلزامياً
- تغيير رموز الأخطاء أو شكل رسائلها
- تشديد التحقق من مدخلات كانت تُقبل سابقاً
التغييرات الهادئة هي الأخطر. تحويل السعر من رقم صحيح إلى نص، أو الوقت من التوقيت المحلي إلى التوقيت العالمي، يمرّ من كل فحوصات البناء ويكسر العملاء مع ذلك. وثّق قواعد التسامح (تجاهل الحقول غير المعروفة، والتعامل مع القيم غير المعروفة) في إرشادات واجهتك العامة ليبني العملاء على أساسها.
4. تشغيل عدة إصدارات في الكود
دعم إصدارين لا يعني صيانة قاعدتي كود. النمط الذي ينجح هو نموذج مجال داخلي واحد مع طبقة ترجمة رقيقة لكل إصدار.
- 1الطلبمسار v1 أو v2 أو v3
- 2محوّل الإصداريحوّله إلى مدخل داخلي
- 3الخدمة الأساسيةتنفيذ واحد
- 4محوّل الاستجابةيشكّل المخرج القديم أو الجديد
مثال توضيحي
أبقِ قواعد العمل في الخدمة الأساسية، واحفظ تحويل الطلب والاستجابة لكل إصدار في فئات صغيرة معزولة. عند إنهاء v1 تحذف محولاته ولا يتغير شيء آخر.
تجنب التفرع حسب الإصدار داخل منطق العمل. بمجرد ظهور if ($version === 1) في خدمة، تكون قد صنعت دَيناً تقنياً دائماً لن يجرؤ أحد على إزالته.
نصيحة: أعطِ كل محوّل إصدار اختبارات عقود خاصة به. عندما يغيّر تعديل في النواة استجابة قديمة بالخطأ، تلتقطه هذه الاختبارات قبل أن يلتقطه عميل.
5. سياسة الإيقاف التدريجي والإنهاء
إنهاء إصدار مشكلة تواصل أكثر منها مشكلة تقنية. انشر السياسة قبل أن تحتاج إليها حتى لا يتفاجأ أحد.
تحدد السياسة العملية الحد الأدنى لفترة الدعم (مثلاً اثنا عشر شهراً بعد صدور الإصدار البديل للواجهات الموجهة للجوال)، وكيفية الإعلان عن الإيقاف، وما يحدث في تاريخ الإنهاء.
استخدم الإشارات القابلة للقراءة آلياً أيضاً. ترويستا الاستجابة Deprecation وSunset تخبران مطوري العملاء وأدوات المراقبة لديهم بأن موعداً قادم. وأرفقهما برسائل إلى أصحاب الحسابات الذين تعرفهم من مفاتيح الواجهة.
ثم راقب الحركة. التواريخ في سجل التغييرات لا تنهي الإصدارات، بل انخفاض الاستخدام إلى الصفر. إذا كان عميل كبير ما زال على الإصدار القديم عند الإنهاء، فتواصل معه شخصياً بدلاً من الإغلاق في الموعد.
6. الاختبار ومراقبة التوافق
التوافق يسهل كسره ويصعب ملاحظته. أتمت الفحوصات.
- مقارنة المخطط في التكامل المستمر. قارن مواصفة OpenAPI بآخر نسخة منشورة وأفشل البناء عند أي فرق كاسر.
- اختبارات العقود. سجّل أزواج طلبات واستجابات حقيقية من كل إصدار مدعوم وأعد تشغيلها على كل بناء.
- مقاييس لكل إصدار. تتبع حجم الطلبات ومعدل الأخطاء وزمن الاستجابة حسب الإصدار، وحسب العميل إن أمكن. ارتفاع الأخطاء في إصدار قديم يعني غالباً تراجعاً لا يظهر إلا فيه.
- تعريف العميل. اشترط ترويسة بإصدار التطبيق أو الحزمة لتعرف من يستدعي واجهتك فعلاً.
بهذه العادات يتحول الإصدار من أمل إلى ضمان قابل للقياس.
7. الأسئلة الشائعة
هل أصدّر واجهتي برقم إصدار من اليوم الأول؟
نعم، إذا كان لها عملاء خارجيون أو تطبيقات جوال. البدء بـ /v1 لا يكلف شيئاً تقريباً، أما إضافة الإصدار لاحقاً فتجبر كل عميل قائم على التغيير.
متى أحتاج فعلاً إلى إصدار رئيسي جديد؟
فقط عندما يتعذر إجراء التغيير بشكل إضافي: حذف الحقول أو تغيير أسمائها، أو تغيير الأنواع والمعاني، أو تعديل عقد الأخطاء. حاول جمع التغييرات الكاسرة في إصدار واحد مخطط له.
كم يجب أن أدعم الإصدار القديم؟
يعتمد على من هم عملاؤك. للواجهات الموجهة للجوال، اثنا عشر شهراً أو أكثر بعد صدور البديل أمر شائع. استخدم بيانات الحركة لكل إصدار لتتأكد من انخفاض الاستخدام قبل الإنهاء.
هل يلغي GraphQL الحاجة إلى الإصدارات؟
يقلل الحاجة، لأن العملاء يطلبون الحقول التي يحتاجونها فقط ويمكنك إيقاف الحقول واحداً واحداً. لكنك ما زلت بحاجة إلى سياسة لحذف الحقول وتغيير معانيها.
الخاتمة
إصدار الواجهات الجيد انضباط في معظمه. فضّل التغييرات الإضافية، واختر أسلوباً واحداً وطبّقه بصرامة، واعزل فروق الإصدارات في محولات رقيقة، وانشر سياسة إيقاف، ودع الحركة الفعلية تخبرك متى يكون إنهاء شيء ما آمناً. بذلك تستمر واجهتك في التطور وتبقى تطبيقات عملائك المنشورة تعمل.
في المرة القادمة التي تخطط فيها لتغيير، اسأل أولاً: هل يمكن أن يكون إضافياً؟ كثيراً ما يمكن.
💬 ما أقدم إصدار لواجهتكم ما زال فريقكم يدعمه، وما الذي يُبقيه حياً؟
التعليقات