إصدارات API: متى تكسر التوافق وكيف لا تفعل

تبدأ النقاشات حول إصدارات API من الطرف الخطأ في العادة، أي من موضع رقم الإصدار. وهذا أقل قرار أهمية في الموضوع كله. المهم فعلاً هو معرفة أي التغييرات يستدعي إصداراً جديداً من الأساس، ومعظم الفرق تخطئ هنا في اتجاه التهاون: تُطلق شيئاً تظنه إضافياً بحتاً، فينكسر أحد العملاء.

النموذج الذهني المفيد هو أن واجهتك وعد بما يستطيع المستدعي الاعتماد عليه. والتغيير يكسر التوافق إذا أبطل شيئاً كان مستدعٍ عاقل يعتمد عليه، والمستدعون يعتمدون على أكثر مما يسمح به التوثيق صراحةً.

التغيير الذي يوقع الجميع: إضافة حقل إلى الاستجابة. إنه إضافي، ولا يمكن أن يكسر عميلاً مكتوباً بإتقان، ومع ذلك يكسر عملاء حقيقيين بانتظام، لأن بعضهم يتحقق من الاستجابات بصرامة ويرفض الحقول غير المعروفة. وسواء كان الذنب ذنبك أم ذنبهم فلا قيمة للسؤال منذ اللحظة التي يتوقف فيها تكاملهم ويرن الهاتف.

ما الذي يُعدّ كسراً للتوافق فعلاً

كسر بلا أي التباس: حذف حقل أو إعادة تسميته، وتغيير نوع حقل، وإضافة معامل إلزامي إلى الطلب، وتشديد التحقق، وتغيير معنى قيمة قائمة، أو تغيير رمز حالة يتفرع عليه المستدعي في شيفرته.

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

آمن حقاً: إضافة معامل طلب اختياري جديد، وإضافة نقطة نهاية جديدة، وتخفيف التحقق، وإضافة قيمة جديدة إلى تعداد، لكن بشرط أن يكون العملاء قد أُبلغوا مسبقاً بتوقع قيم غير معروفة وأن تستطيع التحقق من أنهم يعالجونها فعلاً.

القاعدة أن الأمان يعتمد على ما يفعله المستدعون فعلاً، لا على ما تسمح به المواصفة. إن كنت تسيطر على كل عميل فبإمكانك التحقق. وإن لم تكن كذلك، فافترض أن أحدهم يعتمد على الشيء الذي حسبته عرضياً، لأن هذا ما يحدث دائماً.

استراتيجيات إصدارات API وتكلفة كل منها

الإصدار في المسار. أشيع الأساليب، وفضيلته أنه ظاهر للعيان: /v1/orders و /v2/orders موردان مختلفان بوضوح. وتكلفته أنه يشجع على قفزات إصدار للواجهة كلها، فيجرّ تغييرٌ يمس نقطة نهاية واحدة كل شيء معه، ويضطر العملاء إلى الترحيل دفعة واحدة.

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

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

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

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

كيف تجعل الكسر محتملاً

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

قِس من يستخدم ماذا. لا يمكنك سحب إصدار بأمان دون معرفة من لا يزال عليه. سجّل مع كل طلب رقم الإصدار وهوية العميل، حتى يصير الإيقاف حواراً قائماً على أدلة بدل إعلان يُلقى في الظلام.

أعلن بآلية، لا برسالة بريد فقط. تتيح ترويستا الاستجابة Deprecation و Sunset للعميل اكتشاف تاريخ السحب برمجياً، وهذا أدعى للانتباه من رسالة تُرسل إلى عنوان لم يعد أحد يقرأه.

امنح مهلة واقعية. يصون التكاملاتِ أشخاصٌ لديهم أولويات أخرى، وأي موعد نهائي أقصر من دورة إصدارهم سيفوتهم ببساطة. ستة أشهر شائعة لواجهة عامة، وأقل من ذلك معقول مع عدد صغير من الشركاء المعروفين الذين تحدثت إليهم.

سحب إصدار قديم

القياس المذكور أعلاه هو ما يجعل هذه الخطوة ممكنة. أعلن التاريخ، وراقب حركة الطلبات وهي تتراجع، وتواصل بالاسم مع المستدعين الذين لم ينتقلوا بعد.

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

الموقف الصادق هو أن بعض المستدعين لن ينتقلوا إلا حين يتوقف الإصدار القديم عن العمل. خطط لذلك بدل أن تفاجأ به، واحرص على أن يكون شكل الفشل رسالة خطأ واضحة تشرح ما جرى، لا انتهاء مهلة صامتاً.

الإصدار الذي لا تحتاجه

معظم الواجهات الداخلية لا تحتاج إلى إصدارات إطلاقاً، لأنك تسيطر على كل مستدعٍ وتستطيع تغيير الطرفين معاً. وإضافة تفاوض على الإصدار إلى واجهة تستخدمها خدمتان من خدماتك أنت هي آلة تكلفك شيئاً ولا تحميك من شيء.

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

تصمم Mecanik واجهات من هذا النوع وتصونها ضمن عملنا في تطوير البرمجيات. نادراً ما يكون مخطط ترقيم الإصدارات هو القرار المثير للاهتمام؛ أما معرفة أي عملائك لا يزال على الإصدار القديم فهي كذلك دائماً.

الأسئلة الشائعة

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

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

ما هي إصدارات API حسب التاريخ؟ يثبّت المستدعي تاريخاً فيحصل على الواجهة كما كانت تتصرف حينها، كما تفعل Stripe بإصدار افتراضي لكل حساب تستطيع الطلبات الفردية تجاوزه. يمنح العملاء أصغر خطوات ترحيل ممكنة وينقل عبء التوافق إلى قاعدة شيفرتك، التي تصون بعدها التحويلات بين الإصدارات.

كم ينبغي أن تطول مهلة إيقاف API؟ ستة أشهر شائعة لواجهة عامة، وأقل من ذلك معقول مع عدد صغير من الشركاء المعروفين الذين تحدثت إليهم مباشرة. يصون التكاملاتِ أشخاصٌ لديهم أولويات أخرى، لذا فأي مهلة أقصر من دورة إصدارهم ستفوتهم مهما كان الإعلان واضحاً.

هل تحتاج الواجهات الداخلية إلى إصدارات؟ غالباً لا، لأنك تسيطر على كل مستدعٍ وتستطيع تغيير الطرفين معاً. وتصير الإصدارات ضرورية عند النقطة التي لا تعود فيها قادراً على نشر كل المستهلكين دفعة واحدة، سواء تبعوا فريقاً آخر أو دورة إصدار أخرى أو شركة أخرى. هذا هو المُشغّل، لا كون الواجهة عامة.