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