إذاً، إلى أي مدى يمكن أن يكون إصدار واجهة برمجة التطبيقات API صعبًا؟ الحقيقة أنه ليس كذلك، ولكن ما هو صعب هو الحفاظ على بعض العقلانية بتجنب التفريع غير الضروري إلى عدد مذهل من الإصدارات والنسخ المطبقة عبر عشرات من نقاط نهاية واجهة برمجة التطبيقات مع توافق غير واضح.
التغييرات الجذرية سيئة! استخدام إصدار API جيد!
كما يدرك أي شخص قام ببناء API أو يستخدمه بانتظام عاجلاً أم آجلاً، فإن التغييرات الجذرية سيئة للغاية ويمكن أن تكون لطخة خطيرة على API مفيد في غير ذلك. التغيير الجذري هو تغيير في سلوك API يمكن أن يكسر تكامل المستخدم ويؤدي إلى الكثير من الإحباط وفقدان الثقة بين مزود API والمستخدم. تتطلب التغييرات الجذرية أن يتم إبلاغ المستخدمين مسبقًا (مع اعتذارات مصاحبة) بدلاً من التغيير الذي يظهر فجأة، مثل ميزة جديدة ومبهجة. الطريقة لتجنب هذا الإحباط هي نسخ API مع تأكيدات من مالك API بأنه لن يتم إدخال تغييرات مفاجئة ضمن أي نسخة واحدة.
إذاً، كم يمكن أن يكون من الصعب نسخة API؟ الحقيقة أنها ليست صعبة، لكن ما هو صعب هو الحفاظ على بعض الاتزان بعدم التدهور بدون مبرر إلى عدد مثير للحيرة من النسخ والفرعيات المطبقة عبر العشرات من وظائف API مع توافقات غير واضحة.
لقد قدمنا النسخة v1 من API منذ ثلاث سنوات ولم ندرك أنها ستستمر بقوة إلى يومنا هذا. فكيف واصلنا توفير أفضل API لبدء تشغيل البريد الإلكتروني لأكثر من عامين وما زلنا نحافظ على نفس نسخة API؟ هذه الاستقرار ضرورية للمطورين الذين يبنون التطبيقات باستخدام email APIs in cloud infrastructure، حيث البساطة والموثوقية هما الأولوية الأقصى. بينما هناك العديد من الآراء المختلفة حول كيفية نسخ APIs REST، آمل أن تكون قصة نسختنا v1 الهادئة والقوية قد ترشدك في طريقك للحصول على بصيرة نسخة APIs.
الراحة هي الأفضل
حوكمة API
مع اختيار اتفاقية إدارة الإصدارات، كانت لدينا المزيد من الأسئلة. متى سنغير الإصدار؟ ما هو التغيير المكسِّر؟ هل سنعيد إصدار كل واجهة برمجة التطبيقات أم مجرد بعض النقاط النهائية؟ في SparkPost، لدينا فرق متعددة تعمل على أجزاء مختلفة من واجهة برمجة التطبيقات الخاصة بنا. داخل تلك الفرق، يعمل الأشخاص على نقاط نهائية مختلفة في أوقات مختلفة. لذلك، من المهم جداً أن تكون واجهة برمجة التطبيقات الخاصة بنا متسقة في استخدام الاتفاقيات. كان هذا أكبر من مجرد إدارة الإصدارات.
قمنا بإنشاء مجموعة حوكمة تضم مهندسين يمثلون كل فريق، عضوًا من فريق إدارة المنتجات، والرئيس التنفيذي للتكنولوجيا لدينا. هذه المجموعة مسؤولة عن إنشاء وتوثيق وفرض اتفاقيات واجهة برمجة التطبيقات عبر جميع الفرق. كما يأتي قناة Slack الخاصة بالحوكمة في واجهة برمجة التطبيقات في متناول اليد للنقاشات النشطة حول الموضوع.
حددت مجموعة الحوكمة عددًا من الطرق التي يمكن من خلالها إدخال التغييرات إلى واجهة برمجة التطبيقات التي تكون مفيدة للمستخدم ولا تشكل تغييرًا مكسِّرًا. وتشمل هذه:
مورد جديد أو نقطة نهاية واجهة برمجة التطبيقات
مُعلمة اختيارية جديدة
تغيير لنقطة نهاية غير عامة في واجهة برمجة التطبيقات
مفتاح اختياري جديد في جسم JSON POST
مفتاح جديد يتم إرجاعه في جسم JSON response
وعلى النقيض من ذلك، كان التغيير المكسِّر يتضمن أي شيء يمكن أن يكسر تكامل المستخدم مثل:
مُعلمة مطلوبة جديدة
مفتاح جديد مطلوب في أجسام POST
إزالة نقطة نهاية موجودة
إزالة طريقة طلب نقطة نهاية موجودة
سلوك داخلي مادي مختلف لاستدعاء واجهة برمجة التطبيقات – مثل تغيير على السلوك الافتراضي.
النسخة الكبيرة 1.0
عندما قمنا بتوثيق ومناقشة هذه الاتفاقيات، توصلنا أيضًا إلى استنتاج أنه من مصلحة الجميع (بما في ذلك نحن!) تجنب إجراء تغييرات جذرية على API لأن إدارة إصدارات متعددة تضيف قدرًا لا بأس به من العبء. قررنا أن هناك بعض الأشياء التي يجب أن نقوم بإصلاحها في API الخاص بنا قبل الالتزام بـ “v1”.
إرسال بريد إلكتروني بسيط كان يتطلب جهدًا كبيرًا جدًا. للحفاظ على 'الأشياء البسيطة بسيطة' قمنا بتحديث جسم POST لضمان تلبية كل من الحالات البسيطة والمعقدة. كان الشكل الجديد أكثر توافقًا مع المتطلبات المستقبلية أيضًا. ثانياً، قمنا بمعالجة مشكلة في نقطة النهاية الخاصة بالـ Metrics. كانت هذه النقطة النهائية تستخدم معلمة “group_by” التي كانت تقوم بتغيير شكل جسم استجابة GET بحيث يكون المفتاح الأول هو قيمة معلمة group by. لم يكن ذلك يبدو RESTful جدًا، لذلك قمنا بتفكيك كل مجموعة إلى نقطة نهاية منفصلة. وأخيراً، قمنا بتدقيق كل نقطة نهاية وقمنا بإجراء تغييرات طفيفة هنا وهناك لضمان توافقها مع المعايير.
توثيق دقيق
من المهم أن يكون لديك توثيق API دقيق وقابل للاستخدام لتجنب التغييرات التي قد تكون مقصودة أو غير مقصودة. قررنا استخدام نهج بسيط لتوثيق API باستخدام لغة Markdown تسمى API Blueprint وإدارة مستنداتنا في Github. يساهم مجتمعنا في تحسين هذه المستندات مفتوحة المصدر. كما نقوم أيضًا بالحفاظ على مجموعة غير علنية من المستندات في Github خاصة بواجهات وبرامج التوصيل الداخلية.
في البداية، نشرنا مستنداتنا على Apiary، وهي أداة رائعة للنماذج الأولية ونشر مستندات API. ومع ذلك، لم يكن إضافة Apiary إلى موقعنا الإلكتروني يعمل على الأجهزة المحمولة، لذا أصبحنا الآن نستخدم Jekyll لإنشاء مستندات ثابتة بدلاً من ذلك. مستندات SparkPost API الأحدث لدينا الآن تُحمّل بسرعة وتعمل بشكل جيد على الأجهزة المحمولة، وهو الأمر المهم للمطورين الذين ليسوا دائمًا جالسين أمام جهاز الكمبيوتر الخاص بهم.
فصل النشر عن الإصدار
تعلمنا في وقت مبكر حيلة قيمة لفصل عملية النشر عن الإصدار. بهذه الطريقة، من الممكن نشر التغييرات بشكل متكرر عند جاهزيتها من خلال التسليم والنشر المستمرين، ولكننا لا نعلن عنها أو نوثقها بشكل علني دائمًا في نفس الوقت. ليس من غير المألوف أن نقوم بنشر نقطة نهاية API جديدة أو تحسين لنقطة نهاية API موجودة واستخدامها من داخل الواجهة أو مع الأدوات الداخلية قبل أن نقوم بتوثيقها ودعمها علنًا. بهذه الطريقة، يمكننا إجراء بعض التعديلات عليها لتحسين الاستخدام أو الامتثال للمعايير دون القلق بشأن إجراء تغيير مدمّر. بمجرد أن نكون راضين عن التغيير، نضيفه إلى توثيقنا العام.
أوه!
من الإنصاف الاعتراف بأنه كان هناك أوقات لم نرتق فيها إلى مثُلنا العليا "لا تغييرات جذرية" وهذه الأوقات تستحق التعلم منها. في إحدى المناسبات، قررنا أنه سيكون من الأفضل للمستخدمين إذا كان الإعداد الافتراضي لخاصية معينة هو true بدلاً من false. بعد أن نشرنا التغيير، تلقينا عدة شكاوى من المستخدمين لأن السلوك قد تغير بشكل غير متوقع. قمنا بإعادة الوضع إلى ما كان عليه وأضفنا إعدادًا على مستوى الحساب – وهو نهج أكثر ودية للمستخدمين بالتأكيد.
أحيانًا نشعر بالإغراء لإدخال تغييرات جذرية كنتيجة لإصلاح الأخطاء. مع ذلك، قررنا ترك هذه الخصوصيات كما هي بدلاً من المجازفة بإلحاق الأذى بتكاملات العملاء من أجل التناسق.
هناك حالات نادرة حيث اتخذنا القرار الجاد بإجراء تغيير جذري – مثل إيقاف مصدر أو طريقة API – لمصلحة المجتمع الأكبر من المستخدمين وفقط بعد التأكد من أن التأثير على المستخدمين ضئيل أو معدوم. على سبيل المثال، اتخذنا القرار عمدًا لتغيير سلوك الاستجابة لواجهة Suppression API ولكن فقط بعد الموازنة بعناية بين الفوائد والتأثيرات على المجتمع والتواصل بعناية حول التغيير مع مستخدمينا. ومع ذلك، لن نقدم أبدًا على إجراء تغيير قد يكون له تأثير مباشر على إرسال البريد الإلكتروني الإنتاجي لأحد المستخدمين.
