إذاً، إلى أي مدى يمكن أن يكون إصدار واجهة برمجة التطبيقات API صعبًا؟ الحقيقة أنه ليس كذلك، ولكن ما هو صعب هو الحفاظ على بعض العقلانية بتجنب التفريع غير الضروري إلى عدد مذهل من الإصدارات والنسخ المطبقة عبر عشرات من نقاط نهاية واجهة برمجة التطبيقات مع توافق غير واضح.
التغييرات الجذرية سيئة! استخدام إصدار API جيد!
كما يدرك أي شخص قام ببناء API أو يستخدمه بانتظام عاجلاً أم آجلاً، فإن التغييرات الجذرية سيئة للغاية ويمكن أن تكون لطخة خطيرة على API مفيد في غير ذلك. التغيير الجذري هو تغيير في سلوك API يمكن أن يكسر تكامل المستخدم ويؤدي إلى الكثير من الإحباط وفقدان الثقة بين مزود API والمستخدم. تتطلب التغييرات الجذرية أن يتم إبلاغ المستخدمين مسبقًا (مع اعتذارات مصاحبة) بدلاً من التغيير الذي يظهر فجأة، مثل ميزة جديدة ومبهجة. الطريقة لتجنب هذا الإحباط هي نسخ API مع تأكيدات من مالك API بأنه لن يتم إدخال تغييرات مفاجئة ضمن أي نسخة واحدة.
إذاً، كم يمكن أن يكون من الصعب نسخة API؟ الحقيقة أنها ليست صعبة، لكن ما هو صعب هو الحفاظ على بعض الاتزان بعدم التدهور بدون مبرر إلى عدد مثير للحيرة من النسخ والفرعيات المطبقة عبر العشرات من وظائف API مع توافقات غير واضحة.
لقد قدمنا النسخة v1 من API منذ ثلاث سنوات ولم ندرك أنها ستستمر بقوة إلى يومنا هذا. فكيف واصلنا توفير أفضل API لبدء تشغيل البريد الإلكتروني لأكثر من عامين وما زلنا نحافظ على نفس نسخة API؟ هذه الاستقرار ضرورية للمطورين الذين يبنون التطبيقات باستخدام email APIs in cloud infrastructure، حيث البساطة والموثوقية هما الأولوية الأقصى. بينما هناك العديد من الآراء المختلفة حول كيفية نسخ APIs REST، آمل أن تكون قصة نسختنا v1 الهادئة والقوية قد ترشدك في طريقك للحصول على بصيرة نسخة APIs.
الراحة هي الأفضل
حوكمة 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 ولكن فقط بعد الموازنة بعناية بين الفوائد والتأثيرات على المجتمع والتواصل بعناية حول التغيير مع مستخدمينا. ومع ذلك، لن نقدم أبدًا على إجراء تغيير قد يكون له تأثير مباشر على إرسال البريد الإلكتروني الإنتاجي لأحد المستخدمين.
