أفضل الممارسات لإصدار واجهة برمجة التطبيقات RESTful: لماذا تعتبر النسخة 1 الأفضل
كريس مكفادن
24/05/2017
البريد الإلكتروني
1 min read
النقاط الرئيسية
يمنع إصدار واجهة برمجة التطبيقات تغييرات كاسرة ويحتفظ بالثقة بين مقدمي واجهة برمجة التطبيقات والمطورين.
تساعد التقاليد الواضحة للإصدار على تجنب مزيج فوضوي من الإصدارات عبر نقاط النهاية.
تساعد واجهات برمجة التطبيقات RESTful المقترنة بواجهات إصدار بسيطة وواضحة على إبقاء التكاملات بديهية للمطورين.
تضمن مجموعات الحكم التناسق بين الفرق، مما يمنع التغييرات الكاسرة غير المقصودة.
لا تتطلب جميع التغييرات إصدارًا جديدًا - فقط تلك التي تكسر التكاملات الحالية.
تعتبر الوثائق الجيدة ضرورية لتجنب الارتباك ومنع التغييرات الكاسرة غير المقصودة.
يسمح فصل النشر عن الإصدار للفرق باختبار وتعديل نقاط النهاية بأمان قبل الإعلان عنها.
عندما تكون التغييرات الكاسرة لا مفر منها، يجب تقييمها بعناية والتواصل حولها.
أهم النقاط في الأسئلة والأجوبة
لماذا يعتبر إصدار واجهة برمجة التطبيقات (API) مهمًا؟
يمنع التغييرات المفاجئة غير المتوقعة للمطورين الذين يتكاملون مع واجهة برمجة التطبيقات الخاصة بك، ويحمي الثقة، ويضمن استقرارًا طويل الأمد للتطبيقات التي تعتمد على سلوك ثابت.
ما هي التغييرات الكبيرة في واجهة برمجة التطبيقات؟
أي تعديل يغير كيفية تصرف التكاملات الحالية - مثل إزالة نقاط النهاية، أو تغيير القيم الافتراضية، أو إضافة حقول مطلوبة، أو تعديل تنسيقات الاستجابة.
لماذا اختارت SparkPost REST كأساس لواجهة برمجة التطبيقات الخاصة بها؟
يسهل استخدام REST لـ HTTP و JSON على المطورين عبر اللغات (PHP و Ruby و Java وغيرها) الاندماج دون الحاجة إلى معرفة متخصصة بالأنظمة الأساسية.
كيف قررت SparkPost بشأن طريقة إصدارها؟
لقد قيموا إصدار رأس Accept مقابل إصدار URI واختاروا إصدار URI لأنه صريح وبسيط وأكثر صداقة للمطورين.
ما الدور الذي تلعبه مجموعة حكومات واجهة برمجة التطبيقات؟
يضع معايير، يفرض الاتساق، ويمنع الفرق من إدخال تغييرات تتعارض مع الاتفاقيات أو تكسر التوافق.
ما أنواع التغييرات التي لا تعتبر كاسرة؟
إضافة معلمات اختيارية جديدة، تقديم نقاط نهاية جديدة، إضافة مفاتيح جديدة في حمولات JSON، أو تغيير نقاط النهاية غير العامة - أي شيء لا يعطل السلوك القائم.
ما التغييرات التي تعتبر كسرية؟
إضافة المعلمات المطلوبة، إزالة نقاط النهاية، تغيير السلوكيات الافتراضية، تعديل هيكل الاستجابة، أو إدخال حقول JSON المطلوبة.
لماذا تعتبر الوثائق الدقيقة ضرورية؟
إنه يمنع التغييرات غير المقصودة، ويساعد المطورين على فهم السلوك، ويضمن تحديث الفرق لواجهة برمجة التطبيقات بشكل موثوق. استخدمت SparkPost Markdown (API Blueprint) و GitHub للحفاظ على الوضوح والانفتاح.
ما فائدة فصل النشر عن الإصدار؟
يمكن للفرق نشر نقاط النهاية أو التحسينات الجديدة باستمرار داخليًا، واختبارها في سير العمل الحقيقي، وتحسين السلوكيات، والإفراج عنها للجمهور فقط عندما تصبح مستقرة - مما يتجنب التعرض المبكر والمحتمل الخطير.
ماذا يحدث إذا أصبح تغيير جذري ضروريًا؟
يجب أن يكون نادرًا، ومبررًا بمزايا واضحة، تم تقييمه بعناية من حيث تأثيره على المستخدم، ومُبلغ عنه بشكل شامل. مثال: تعديل واجهة برمجة تطبيقات الكبح فقط بعد تأكيد التأثير الأدنى وتقديم إشعار.
إذًا، ما مدى صعوبة إصدار واجهة برمجة التطبيقات؟ الحقيقة هي أنه ليس من الصعب، ولكن ما هو صعب هو الحفاظ على بعض العقلانية من خلال عدم الانزلاق بشكل غير ضروري إلى عدد مذهل من الإصدارات والإصدارات الفرعية المطبقة عبر العشرات من نقاط نهاية واجهة برمجة التطبيقات ذات التوافقات غير الواضحة.
إذًا، ما مدى صعوبة إصدار واجهة برمجة التطبيقات؟ الحقيقة هي أنه ليس من الصعب، ولكن ما هو صعب هو الحفاظ على بعض العقلانية من خلال عدم الانزلاق بشكل غير ضروري إلى عدد مذهل من الإصدارات والإصدارات الفرعية المطبقة عبر العشرات من نقاط نهاية واجهة برمجة التطبيقات ذات التوافقات غير الواضحة.
إذًا، ما مدى صعوبة إصدار واجهة برمجة التطبيقات؟ الحقيقة هي أنه ليس من الصعب، ولكن ما هو صعب هو الحفاظ على بعض العقلانية من خلال عدم الانزلاق بشكل غير ضروري إلى عدد مذهل من الإصدارات والإصدارات الفرعية المطبقة عبر العشرات من نقاط نهاية واجهة برمجة التطبيقات ذات التوافقات غير الواضحة.
إيه!
من العدل أن نعترف أنه كانت هناك أوقات لم نصل فيها إلى مثالية "عدم وجود تغييرات تضر" والتي تستحق التعلم منها. في إحدى المرات، قررنا أنه سيكون أفضل للمستخدمين إذا كانت خاصية معينة افتراضية على true بدلاً من false. بعد طرح التغيير، تلقينا العديد من الشكاوى من المستخدمين لأن السلوك قد تغير بشكل غير متوقع. أعدنا التغيير وأضفنا إعداداً على مستوى الحساب – وهو بالتأكيد نهج أكثر ملاءمة للمستخدمين.
بينما نكون أحياناً مغريين لتقديم تغييرات تضر نتيجة لإصلاحات الأخطاء. ومع ذلك، قررنا ترك هذه الخصوصيات كما هي بدلاً من المخاطرة بتعطيل تكاملات العملاء من أجل التناسق.
هناك حالات نادرة اتخذنا فيها القرار الجاد بإجراء تغيير مؤلم – مثل إلغاء مورد أو طريقة واجهة برمجة التطبيقات – في مصلحة المجتمع الأكبر من المستخدمين، فقط بعد التأكد من أن هناك تأثيراً قليلاً أو معدوماً على المستخدمين. على سبيل المثال، قررنا بشكل متعمد تغيير سلوك استجابة واجهة برمجة التطبيقات الخاصة بالإخفاء، ولكن فقط بعد دراسة الفوائد والتأثيرات على المجتمع بعناية والتواصل بعناية حول هذا التغيير مع مستخدمينا. ومع ذلك، لن نقوم أبداً بإدخال تغيير يحمل إمكانية نادرة لتأثير مباشر على إرسال بريد المستخدم الإلكتروني الإنتاجي.
من العدل أن نعترف أنه كانت هناك أوقات لم نصل فيها إلى مثالية "عدم وجود تغييرات تضر" والتي تستحق التعلم منها. في إحدى المرات، قررنا أنه سيكون أفضل للمستخدمين إذا كانت خاصية معينة افتراضية على true بدلاً من false. بعد طرح التغيير، تلقينا العديد من الشكاوى من المستخدمين لأن السلوك قد تغير بشكل غير متوقع. أعدنا التغيير وأضفنا إعداداً على مستوى الحساب – وهو بالتأكيد نهج أكثر ملاءمة للمستخدمين.
بينما نكون أحياناً مغريين لتقديم تغييرات تضر نتيجة لإصلاحات الأخطاء. ومع ذلك، قررنا ترك هذه الخصوصيات كما هي بدلاً من المخاطرة بتعطيل تكاملات العملاء من أجل التناسق.
هناك حالات نادرة اتخذنا فيها القرار الجاد بإجراء تغيير مؤلم – مثل إلغاء مورد أو طريقة واجهة برمجة التطبيقات – في مصلحة المجتمع الأكبر من المستخدمين، فقط بعد التأكد من أن هناك تأثيراً قليلاً أو معدوماً على المستخدمين. على سبيل المثال، قررنا بشكل متعمد تغيير سلوك استجابة واجهة برمجة التطبيقات الخاصة بالإخفاء، ولكن فقط بعد دراسة الفوائد والتأثيرات على المجتمع بعناية والتواصل بعناية حول هذا التغيير مع مستخدمينا. ومع ذلك، لن نقوم أبداً بإدخال تغيير يحمل إمكانية نادرة لتأثير مباشر على إرسال بريد المستخدم الإلكتروني الإنتاجي.
من العدل أن نعترف أنه كانت هناك أوقات لم نصل فيها إلى مثالية "عدم وجود تغييرات تضر" والتي تستحق التعلم منها. في إحدى المرات، قررنا أنه سيكون أفضل للمستخدمين إذا كانت خاصية معينة افتراضية على true بدلاً من false. بعد طرح التغيير، تلقينا العديد من الشكاوى من المستخدمين لأن السلوك قد تغير بشكل غير متوقع. أعدنا التغيير وأضفنا إعداداً على مستوى الحساب – وهو بالتأكيد نهج أكثر ملاءمة للمستخدمين.
بينما نكون أحياناً مغريين لتقديم تغييرات تضر نتيجة لإصلاحات الأخطاء. ومع ذلك، قررنا ترك هذه الخصوصيات كما هي بدلاً من المخاطرة بتعطيل تكاملات العملاء من أجل التناسق.
هناك حالات نادرة اتخذنا فيها القرار الجاد بإجراء تغيير مؤلم – مثل إلغاء مورد أو طريقة واجهة برمجة التطبيقات – في مصلحة المجتمع الأكبر من المستخدمين، فقط بعد التأكد من أن هناك تأثيراً قليلاً أو معدوماً على المستخدمين. على سبيل المثال، قررنا بشكل متعمد تغيير سلوك استجابة واجهة برمجة التطبيقات الخاصة بالإخفاء، ولكن فقط بعد دراسة الفوائد والتأثيرات على المجتمع بعناية والتواصل بعناية حول هذا التغيير مع مستخدمينا. ومع ذلك، لن نقوم أبداً بإدخال تغيير يحمل إمكانية نادرة لتأثير مباشر على إرسال بريد المستخدم الإلكتروني الإنتاجي.
تغييرات كبيرة سيئة! إصدار API جيد!
كما يدرك أي شخص قام ببناء أو يستخدم API بانتظام عاجلاً أم آجلاً، فإن التغييرات الجذرية تكون سيئة جداً ويمكن أن تكون عيباً خطيراً على API المساعدة. التغيير الجذري هو تغيير في سلوك API يمكن أن يكسر تكامل المستخدم ويؤدي إلى الكثير من الإحباط وفقدان الثقة بين مزود API والمستخدم. تتطلب التغييرات الجذرية أن يتم إبلاغ المستخدمين مسبقًا (مع الاعتذار المرافق) بدلاً من تغيير يظهر فجأة، مثل ميزة جديدة رائعة. الطريقة لتجنب هذا الإحباط هي إصدار API مع ضمانات من مالك API بأنه لن يتم إدخال تغييرات مفاجئة ضمن أي إصدار واحد.
فما مدى صعوبة إصدار API؟ الحقيقة هي أن الأمر ليس صعبًا، لكن ما هو صعب هو الحفاظ على بعض العقلانية بعدم الانزلاق بلا داعٍ إلى عدد dizzying من الإصدارات والتحديثات الفرعية المطبقة عبر العشرات من نقاط نهاية API مع عدم وضوح التوافقات.
لقد قدمنا الإصدار v1 من API قبل ثلاث سنوات ولم ندرك أنه سيستمر بهذا القوة حتى اليوم. كيف استمررنا في تقديم أفضل API لتسليم البريد الإلكتروني لأكثر من عامين لكن لا زلنا نحافظ على نفس إصدار API؟ هذه الاستقرار أمر حاسم للمطورين الذين يبنون تطبيقات باستخدام APIs البريد الإلكتروني في البنية التحتية السحابية، حيث تعد الموثوقية والتناسق هما الأهم. بينما هناك آراء مختلفة حول كيفية إصدار REST APIs، أمل أن تساعدك قصة إصدارنا المتواضع ولكن القوي v1 في طريقك إلى التنوير في إصدار API.
كما يدرك أي شخص قام ببناء أو يستخدم API بانتظام عاجلاً أم آجلاً، فإن التغييرات الجذرية تكون سيئة جداً ويمكن أن تكون عيباً خطيراً على API المساعدة. التغيير الجذري هو تغيير في سلوك API يمكن أن يكسر تكامل المستخدم ويؤدي إلى الكثير من الإحباط وفقدان الثقة بين مزود API والمستخدم. تتطلب التغييرات الجذرية أن يتم إبلاغ المستخدمين مسبقًا (مع الاعتذار المرافق) بدلاً من تغيير يظهر فجأة، مثل ميزة جديدة رائعة. الطريقة لتجنب هذا الإحباط هي إصدار API مع ضمانات من مالك API بأنه لن يتم إدخال تغييرات مفاجئة ضمن أي إصدار واحد.
فما مدى صعوبة إصدار API؟ الحقيقة هي أن الأمر ليس صعبًا، لكن ما هو صعب هو الحفاظ على بعض العقلانية بعدم الانزلاق بلا داعٍ إلى عدد dizzying من الإصدارات والتحديثات الفرعية المطبقة عبر العشرات من نقاط نهاية API مع عدم وضوح التوافقات.
لقد قدمنا الإصدار v1 من API قبل ثلاث سنوات ولم ندرك أنه سيستمر بهذا القوة حتى اليوم. كيف استمررنا في تقديم أفضل API لتسليم البريد الإلكتروني لأكثر من عامين لكن لا زلنا نحافظ على نفس إصدار API؟ هذه الاستقرار أمر حاسم للمطورين الذين يبنون تطبيقات باستخدام APIs البريد الإلكتروني في البنية التحتية السحابية، حيث تعد الموثوقية والتناسق هما الأهم. بينما هناك آراء مختلفة حول كيفية إصدار REST APIs، أمل أن تساعدك قصة إصدارنا المتواضع ولكن القوي v1 في طريقك إلى التنوير في إصدار API.
كما يدرك أي شخص قام ببناء أو يستخدم API بانتظام عاجلاً أم آجلاً، فإن التغييرات الجذرية تكون سيئة جداً ويمكن أن تكون عيباً خطيراً على API المساعدة. التغيير الجذري هو تغيير في سلوك API يمكن أن يكسر تكامل المستخدم ويؤدي إلى الكثير من الإحباط وفقدان الثقة بين مزود API والمستخدم. تتطلب التغييرات الجذرية أن يتم إبلاغ المستخدمين مسبقًا (مع الاعتذار المرافق) بدلاً من تغيير يظهر فجأة، مثل ميزة جديدة رائعة. الطريقة لتجنب هذا الإحباط هي إصدار API مع ضمانات من مالك API بأنه لن يتم إدخال تغييرات مفاجئة ضمن أي إصدار واحد.
فما مدى صعوبة إصدار API؟ الحقيقة هي أن الأمر ليس صعبًا، لكن ما هو صعب هو الحفاظ على بعض العقلانية بعدم الانزلاق بلا داعٍ إلى عدد dizzying من الإصدارات والتحديثات الفرعية المطبقة عبر العشرات من نقاط نهاية API مع عدم وضوح التوافقات.
لقد قدمنا الإصدار v1 من API قبل ثلاث سنوات ولم ندرك أنه سيستمر بهذا القوة حتى اليوم. كيف استمررنا في تقديم أفضل API لتسليم البريد الإلكتروني لأكثر من عامين لكن لا زلنا نحافظ على نفس إصدار API؟ هذه الاستقرار أمر حاسم للمطورين الذين يبنون تطبيقات باستخدام APIs البريد الإلكتروني في البنية التحتية السحابية، حيث تعد الموثوقية والتناسق هما الأهم. بينما هناك آراء مختلفة حول كيفية إصدار REST APIs، أمل أن تساعدك قصة إصدارنا المتواضع ولكن القوي v1 في طريقك إلى التنوير في إصدار API.
أفضل استراحة
تعود واجهة برمجة تطبيقات SparkPost إلى الفترة التي كنا فيها Message Systems، قبل مغامراتنا في السحابة. في ذلك الوقت كنا منشغلين بإجراء التحضيرات النهائية لإطلاق النسخة التجريبية من Momentum 4. كانت هذه ترقية رئيسية إلى النسخة 3.x، موجهنا الرائد في أنظمة البريد على الموقع. تضمنت Momentum 4 واجهة مستخدم جديدة بالكامل، وتحليلات في الوقت الحقيقي، والأهم من ذلك واجهة برمجة تطبيقات ويب جديدة لحقن الرسائل وإنشائها، وإدارة القوالب، والحصول على مقاييس البريد الإلكتروني. كانت رؤيتنا هي هيكلية تعتمد على واجهة برمجة التطبيقات أولاً - حيث كانت حتى واجهة المستخدم تتفاعل مع نقاط نهاية واجهة برمجة التطبيقات.
كانت واحدة من أوائل وأفضل القرارات التي اتخذناها هي اعتماد أسلوب RESTful. منذ أواخر 2000، فإن تحويل الحالة التمثيلية (REST) كمعيار لك واجهات برمجة التطبيقات السحابية. استخدام HTTP وJSON يجعل من السهل على المطورين، بغض النظر عن لغة البرمجة التي يستخدمونها - PHP وRuby وJava - الاندماج مع واجهة برمجة التطبيقات الخاصة بنا دون الحاجة إلى معرفة أو الاهتمام بتكنولوجيتنا الأساسية. ومع ذلك، فإن بناء واجهات برمجة التطبيقات السحابية على نطاق واسع يمكن أن يقدم تحديات غير متوقعة في البنية التحتية، مثل الحدود الخاصة بتوسيع DNS التي واجهناها في AWS عند التعامل مع حركة مرور واجهة برمجة التطبيقات عالية الحجم.
كان اختيار استخدام هيكلية RESTful سهلاً. لكن كان اختيار تقليد النسخ ليس بالسهل. في البداية لم نتخذ قرار بشأن مسألة النسخ بعدم نسخ النسخة التجريبية على الإطلاق. ومع ذلك، في غضون بضعة أشهر كانت النسخة التجريبية في أيدي بعض العملاء وبدأنا في بناء خدمة السحابة لدينا. حان وقت النسخ. قمنا بتقييم تقليدي نسخ.
نهج النسخ | كيف يعمل | التجارة-off |
|---|---|---|
نسخة URI | النسخة مضمنة في مسار نقطة النهاية | واضحة وسهلة الفهم |
نسخة رأس Accept | النسخة تم تمريرها عبر رأس HTTP | أقل ظهورًا، وأكثر تعقيدًا للمطورين |
كانت الخيار الأول هو وضع النسخة مباشرة في URI والثاني هو استخدام رأس Accept. الخيار الأول أكثر وضوحًا وأقل تعقيدًا، مما يجعله أسهل للمطورين. نظرًا لأننا نحب المطورين، كانت هذه هي الخيار المنطقي.
تعود واجهة برمجة تطبيقات SparkPost إلى الفترة التي كنا فيها Message Systems، قبل مغامراتنا في السحابة. في ذلك الوقت كنا منشغلين بإجراء التحضيرات النهائية لإطلاق النسخة التجريبية من Momentum 4. كانت هذه ترقية رئيسية إلى النسخة 3.x، موجهنا الرائد في أنظمة البريد على الموقع. تضمنت Momentum 4 واجهة مستخدم جديدة بالكامل، وتحليلات في الوقت الحقيقي، والأهم من ذلك واجهة برمجة تطبيقات ويب جديدة لحقن الرسائل وإنشائها، وإدارة القوالب، والحصول على مقاييس البريد الإلكتروني. كانت رؤيتنا هي هيكلية تعتمد على واجهة برمجة التطبيقات أولاً - حيث كانت حتى واجهة المستخدم تتفاعل مع نقاط نهاية واجهة برمجة التطبيقات.
كانت واحدة من أوائل وأفضل القرارات التي اتخذناها هي اعتماد أسلوب RESTful. منذ أواخر 2000، فإن تحويل الحالة التمثيلية (REST) كمعيار لك واجهات برمجة التطبيقات السحابية. استخدام HTTP وJSON يجعل من السهل على المطورين، بغض النظر عن لغة البرمجة التي يستخدمونها - PHP وRuby وJava - الاندماج مع واجهة برمجة التطبيقات الخاصة بنا دون الحاجة إلى معرفة أو الاهتمام بتكنولوجيتنا الأساسية. ومع ذلك، فإن بناء واجهات برمجة التطبيقات السحابية على نطاق واسع يمكن أن يقدم تحديات غير متوقعة في البنية التحتية، مثل الحدود الخاصة بتوسيع DNS التي واجهناها في AWS عند التعامل مع حركة مرور واجهة برمجة التطبيقات عالية الحجم.
كان اختيار استخدام هيكلية RESTful سهلاً. لكن كان اختيار تقليد النسخ ليس بالسهل. في البداية لم نتخذ قرار بشأن مسألة النسخ بعدم نسخ النسخة التجريبية على الإطلاق. ومع ذلك، في غضون بضعة أشهر كانت النسخة التجريبية في أيدي بعض العملاء وبدأنا في بناء خدمة السحابة لدينا. حان وقت النسخ. قمنا بتقييم تقليدي نسخ.
نهج النسخ | كيف يعمل | التجارة-off |
|---|---|---|
نسخة URI | النسخة مضمنة في مسار نقطة النهاية | واضحة وسهلة الفهم |
نسخة رأس Accept | النسخة تم تمريرها عبر رأس HTTP | أقل ظهورًا، وأكثر تعقيدًا للمطورين |
كانت الخيار الأول هو وضع النسخة مباشرة في URI والثاني هو استخدام رأس Accept. الخيار الأول أكثر وضوحًا وأقل تعقيدًا، مما يجعله أسهل للمطورين. نظرًا لأننا نحب المطورين، كانت هذه هي الخيار المنطقي.
تعود واجهة برمجة تطبيقات SparkPost إلى الفترة التي كنا فيها Message Systems، قبل مغامراتنا في السحابة. في ذلك الوقت كنا منشغلين بإجراء التحضيرات النهائية لإطلاق النسخة التجريبية من Momentum 4. كانت هذه ترقية رئيسية إلى النسخة 3.x، موجهنا الرائد في أنظمة البريد على الموقع. تضمنت Momentum 4 واجهة مستخدم جديدة بالكامل، وتحليلات في الوقت الحقيقي، والأهم من ذلك واجهة برمجة تطبيقات ويب جديدة لحقن الرسائل وإنشائها، وإدارة القوالب، والحصول على مقاييس البريد الإلكتروني. كانت رؤيتنا هي هيكلية تعتمد على واجهة برمجة التطبيقات أولاً - حيث كانت حتى واجهة المستخدم تتفاعل مع نقاط نهاية واجهة برمجة التطبيقات.
كانت واحدة من أوائل وأفضل القرارات التي اتخذناها هي اعتماد أسلوب RESTful. منذ أواخر 2000، فإن تحويل الحالة التمثيلية (REST) كمعيار لك واجهات برمجة التطبيقات السحابية. استخدام HTTP وJSON يجعل من السهل على المطورين، بغض النظر عن لغة البرمجة التي يستخدمونها - PHP وRuby وJava - الاندماج مع واجهة برمجة التطبيقات الخاصة بنا دون الحاجة إلى معرفة أو الاهتمام بتكنولوجيتنا الأساسية. ومع ذلك، فإن بناء واجهات برمجة التطبيقات السحابية على نطاق واسع يمكن أن يقدم تحديات غير متوقعة في البنية التحتية، مثل الحدود الخاصة بتوسيع DNS التي واجهناها في AWS عند التعامل مع حركة مرور واجهة برمجة التطبيقات عالية الحجم.
كان اختيار استخدام هيكلية RESTful سهلاً. لكن كان اختيار تقليد النسخ ليس بالسهل. في البداية لم نتخذ قرار بشأن مسألة النسخ بعدم نسخ النسخة التجريبية على الإطلاق. ومع ذلك، في غضون بضعة أشهر كانت النسخة التجريبية في أيدي بعض العملاء وبدأنا في بناء خدمة السحابة لدينا. حان وقت النسخ. قمنا بتقييم تقليدي نسخ.
نهج النسخ | كيف يعمل | التجارة-off |
|---|---|---|
نسخة URI | النسخة مضمنة في مسار نقطة النهاية | واضحة وسهلة الفهم |
نسخة رأس Accept | النسخة تم تمريرها عبر رأس HTTP | أقل ظهورًا، وأكثر تعقيدًا للمطورين |
كانت الخيار الأول هو وضع النسخة مباشرة في URI والثاني هو استخدام رأس Accept. الخيار الأول أكثر وضوحًا وأقل تعقيدًا، مما يجعله أسهل للمطورين. نظرًا لأننا نحب المطورين، كانت هذه هي الخيار المنطقي.
حوكمة واجهة برمجة التطبيقات
مع اختيار تقليد النسخ لدينا، كانت لدينا المزيد من الأسئلة. متى سنقوم بزيادة النسخة؟ ما هو التغيير الذي يعتبر كسرًا؟ هل سنعيد إصدار API بالكامل أم مجرد نقاط نهاية معينة؟ في SparkPost، لدينا عدة فرق تعمل على أجزاء مختلفة من واجهة برمجة التطبيقات الخاصة بنا. ضمن تلك الفرق، يعمل الأشخاص على نقاط نهاية مختلفة في أوقات مختلفة. لذلك، من المهم جدًا أن تكون واجهة برمجة التطبيقات الخاصة بنا متسقة في استخدام التقليد. كان هذا أكبر من مجرد النسخ.
أنشأنا مجموعة حوكمة تضم مهندسين يمثلون كل فريق، وعضو من فريق إدارة المنتجات، ورئيسنا التنفيذي للتكنولوجيا. هذه المجموعة مسؤولة عن إنشاء وتوثيق وتنفيذ تقاليد واجهة برمجة التطبيقات الخاصة بنا عبر جميع الفرق. كما أن قناة Slack لحوكمة واجهة برمجة التطبيقات مفيدة للنقاشات الحيوية حول هذا الموضوع.
حددت مجموعة الحوكمة عددًا من الطرق التي يمكن من خلالها إدخال تغييرات على واجهة برمجة التطبيقات تفيد المستخدم ولا تشكل تغييرًا كاسرًا.
نوع التغيير | هل يُعتبر كسرًا؟ | السبب |
|---|---|---|
موارد جديدة أو نقطة نهاية | لا | لا تؤثر على التكاملات الحالية |
معامل اختياري جديد | لا | تظل الطلبات الحالية صالحة |
مفتاح JSON اختياري جديد | لا | يمكن للعملاء تجاهله بأمان |
حقل استجابة جديد | لا | متوافق مع المستهلكين |
معامل مطلوب جديد | نعم | يكسر الطلبات الحالية |
مفتاح POST مطلوب جديد | نعم | يلغي الأحمال الحالية |
إزالة نقطة نهاية | نعم | تفشل التكاملات الحالية |
تغيير السلوك الافتراضي | نعم | يغير النتائج المتوقعة |
تشمل هذه:
موارد جديدة أو نقطة نهاية API
معامل اختياري جديد
تغيير لنقطة نهاية API غير عامة
مفتاح اختياري جديد في جسم POST JSON
مفتاح جديد يتم الإرجاع في جسم استجابة JSON
وفي المقابل، كان أي تغيير كاسر يتضمن أي شيء يمكن أن يكسر تكامل المستخدم مثل:
معامل مطلوب جديد
مفتاح مطلوب جديد في أجسام POST
إزالة نقطة نهاية موجودة
إزالة طريقة طلب نقطة نهاية موجودة
سلوك داخلي مختلف بشكل مادي لاستدعاء API – مثل تغيير السلوك الافتراضي.
مع اختيار تقليد النسخ لدينا، كانت لدينا المزيد من الأسئلة. متى سنقوم بزيادة النسخة؟ ما هو التغيير الذي يعتبر كسرًا؟ هل سنعيد إصدار API بالكامل أم مجرد نقاط نهاية معينة؟ في SparkPost، لدينا عدة فرق تعمل على أجزاء مختلفة من واجهة برمجة التطبيقات الخاصة بنا. ضمن تلك الفرق، يعمل الأشخاص على نقاط نهاية مختلفة في أوقات مختلفة. لذلك، من المهم جدًا أن تكون واجهة برمجة التطبيقات الخاصة بنا متسقة في استخدام التقليد. كان هذا أكبر من مجرد النسخ.
أنشأنا مجموعة حوكمة تضم مهندسين يمثلون كل فريق، وعضو من فريق إدارة المنتجات، ورئيسنا التنفيذي للتكنولوجيا. هذه المجموعة مسؤولة عن إنشاء وتوثيق وتنفيذ تقاليد واجهة برمجة التطبيقات الخاصة بنا عبر جميع الفرق. كما أن قناة Slack لحوكمة واجهة برمجة التطبيقات مفيدة للنقاشات الحيوية حول هذا الموضوع.
حددت مجموعة الحوكمة عددًا من الطرق التي يمكن من خلالها إدخال تغييرات على واجهة برمجة التطبيقات تفيد المستخدم ولا تشكل تغييرًا كاسرًا.
نوع التغيير | هل يُعتبر كسرًا؟ | السبب |
|---|---|---|
موارد جديدة أو نقطة نهاية | لا | لا تؤثر على التكاملات الحالية |
معامل اختياري جديد | لا | تظل الطلبات الحالية صالحة |
مفتاح JSON اختياري جديد | لا | يمكن للعملاء تجاهله بأمان |
حقل استجابة جديد | لا | متوافق مع المستهلكين |
معامل مطلوب جديد | نعم | يكسر الطلبات الحالية |
مفتاح POST مطلوب جديد | نعم | يلغي الأحمال الحالية |
إزالة نقطة نهاية | نعم | تفشل التكاملات الحالية |
تغيير السلوك الافتراضي | نعم | يغير النتائج المتوقعة |
تشمل هذه:
موارد جديدة أو نقطة نهاية API
معامل اختياري جديد
تغيير لنقطة نهاية API غير عامة
مفتاح اختياري جديد في جسم POST JSON
مفتاح جديد يتم الإرجاع في جسم استجابة JSON
وفي المقابل، كان أي تغيير كاسر يتضمن أي شيء يمكن أن يكسر تكامل المستخدم مثل:
معامل مطلوب جديد
مفتاح مطلوب جديد في أجسام POST
إزالة نقطة نهاية موجودة
إزالة طريقة طلب نقطة نهاية موجودة
سلوك داخلي مختلف بشكل مادي لاستدعاء API – مثل تغيير السلوك الافتراضي.
مع اختيار تقليد النسخ لدينا، كانت لدينا المزيد من الأسئلة. متى سنقوم بزيادة النسخة؟ ما هو التغيير الذي يعتبر كسرًا؟ هل سنعيد إصدار API بالكامل أم مجرد نقاط نهاية معينة؟ في SparkPost، لدينا عدة فرق تعمل على أجزاء مختلفة من واجهة برمجة التطبيقات الخاصة بنا. ضمن تلك الفرق، يعمل الأشخاص على نقاط نهاية مختلفة في أوقات مختلفة. لذلك، من المهم جدًا أن تكون واجهة برمجة التطبيقات الخاصة بنا متسقة في استخدام التقليد. كان هذا أكبر من مجرد النسخ.
أنشأنا مجموعة حوكمة تضم مهندسين يمثلون كل فريق، وعضو من فريق إدارة المنتجات، ورئيسنا التنفيذي للتكنولوجيا. هذه المجموعة مسؤولة عن إنشاء وتوثيق وتنفيذ تقاليد واجهة برمجة التطبيقات الخاصة بنا عبر جميع الفرق. كما أن قناة Slack لحوكمة واجهة برمجة التطبيقات مفيدة للنقاشات الحيوية حول هذا الموضوع.
حددت مجموعة الحوكمة عددًا من الطرق التي يمكن من خلالها إدخال تغييرات على واجهة برمجة التطبيقات تفيد المستخدم ولا تشكل تغييرًا كاسرًا.
نوع التغيير | هل يُعتبر كسرًا؟ | السبب |
|---|---|---|
موارد جديدة أو نقطة نهاية | لا | لا تؤثر على التكاملات الحالية |
معامل اختياري جديد | لا | تظل الطلبات الحالية صالحة |
مفتاح JSON اختياري جديد | لا | يمكن للعملاء تجاهله بأمان |
حقل استجابة جديد | لا | متوافق مع المستهلكين |
معامل مطلوب جديد | نعم | يكسر الطلبات الحالية |
مفتاح POST مطلوب جديد | نعم | يلغي الأحمال الحالية |
إزالة نقطة نهاية | نعم | تفشل التكاملات الحالية |
تغيير السلوك الافتراضي | نعم | يغير النتائج المتوقعة |
تشمل هذه:
موارد جديدة أو نقطة نهاية API
معامل اختياري جديد
تغيير لنقطة نهاية API غير عامة
مفتاح اختياري جديد في جسم POST JSON
مفتاح جديد يتم الإرجاع في جسم استجابة JSON
وفي المقابل، كان أي تغيير كاسر يتضمن أي شيء يمكن أن يكسر تكامل المستخدم مثل:
معامل مطلوب جديد
مفتاح مطلوب جديد في أجسام POST
إزالة نقطة نهاية موجودة
إزالة طريقة طلب نقطة نهاية موجودة
سلوك داخلي مختلف بشكل مادي لاستدعاء API – مثل تغيير السلوك الافتراضي.
الضخم 1.0
كما وثقنا وناقشنا هذه الاتفاقيات، توصلنا أيضًا إلى استنتاج أنه كان من مصلحة الجميع (بما في ذلك مصلحتنا!) تجنب إجراء تغييرات جذرية على واجهة برمجة التطبيقات نظرًا لأن إدارة إصدارات متعددة تضيف الكثير من العبء. قررنا أن هناك بعض الأشياء التي يجب علينا إصلاحها في واجهة برمجة التطبيقات الخاصة بنا قبل الالتزام بـ “v1”.
كان إرسال بريد إلكتروني بسيط يتطلب جهدًا كبيرًا. للـ “احتفاظ بالأمور البسيطة بسيطة” قمنا بتحديث جسم POST لضمان استيعاب كل من الحالات البسيطة والمعقدة. كان التنسيق الجديد أكثر أمانًا للمستقبل أيضًا. ثانيًا، عالجنا المشكلة المتعلقة بنقطة النهاية الخاصة بالمقاييس. كانت هذه النقطة تستخدم بارامتر “group_by” الذي كان يغير تنسيق جسم استجابة GET بحيث تكون المفتاح الأول هو قيمة بارامتر المجموعة. لم يبدو ذلك مطابقًا لمبادئ REST لذا قسمنا كل مجموعة إلى نقطة نهاية منفصلة. أخيرًا، قمنا بمراجعة كل نقطة نهاية وأجرينا تغييرات طفيفة هنا وهناك لضمان توافقها مع المعايير.
كما وثقنا وناقشنا هذه الاتفاقيات، توصلنا أيضًا إلى استنتاج أنه كان من مصلحة الجميع (بما في ذلك مصلحتنا!) تجنب إجراء تغييرات جذرية على واجهة برمجة التطبيقات نظرًا لأن إدارة إصدارات متعددة تضيف الكثير من العبء. قررنا أن هناك بعض الأشياء التي يجب علينا إصلاحها في واجهة برمجة التطبيقات الخاصة بنا قبل الالتزام بـ “v1”.
كان إرسال بريد إلكتروني بسيط يتطلب جهدًا كبيرًا. للـ “احتفاظ بالأمور البسيطة بسيطة” قمنا بتحديث جسم POST لضمان استيعاب كل من الحالات البسيطة والمعقدة. كان التنسيق الجديد أكثر أمانًا للمستقبل أيضًا. ثانيًا، عالجنا المشكلة المتعلقة بنقطة النهاية الخاصة بالمقاييس. كانت هذه النقطة تستخدم بارامتر “group_by” الذي كان يغير تنسيق جسم استجابة GET بحيث تكون المفتاح الأول هو قيمة بارامتر المجموعة. لم يبدو ذلك مطابقًا لمبادئ REST لذا قسمنا كل مجموعة إلى نقطة نهاية منفصلة. أخيرًا، قمنا بمراجعة كل نقطة نهاية وأجرينا تغييرات طفيفة هنا وهناك لضمان توافقها مع المعايير.
كما وثقنا وناقشنا هذه الاتفاقيات، توصلنا أيضًا إلى استنتاج أنه كان من مصلحة الجميع (بما في ذلك مصلحتنا!) تجنب إجراء تغييرات جذرية على واجهة برمجة التطبيقات نظرًا لأن إدارة إصدارات متعددة تضيف الكثير من العبء. قررنا أن هناك بعض الأشياء التي يجب علينا إصلاحها في واجهة برمجة التطبيقات الخاصة بنا قبل الالتزام بـ “v1”.
كان إرسال بريد إلكتروني بسيط يتطلب جهدًا كبيرًا. للـ “احتفاظ بالأمور البسيطة بسيطة” قمنا بتحديث جسم POST لضمان استيعاب كل من الحالات البسيطة والمعقدة. كان التنسيق الجديد أكثر أمانًا للمستقبل أيضًا. ثانيًا، عالجنا المشكلة المتعلقة بنقطة النهاية الخاصة بالمقاييس. كانت هذه النقطة تستخدم بارامتر “group_by” الذي كان يغير تنسيق جسم استجابة GET بحيث تكون المفتاح الأول هو قيمة بارامتر المجموعة. لم يبدو ذلك مطابقًا لمبادئ REST لذا قسمنا كل مجموعة إلى نقطة نهاية منفصلة. أخيرًا، قمنا بمراجعة كل نقطة نهاية وأجرينا تغييرات طفيفة هنا وهناك لضمان توافقها مع المعايير.
توثيق دقيق
من المهم أن يكون لديك وثائق API دقيقة وقابلة للاستخدام لتجنب التغييرات المفاجئة، سواء كانت متعمدة أو غير متعمدة. قررنا استخدام نهج بسيط لوثائق API باستخدام لغة Markdown تُسمى API Blueprint و إدارة مستنداتنا في Github. يساهم مجتمعنا ويتحسن في هذه الوثائق المفتوحة المصدر. كما نحافظ على مجموعة غير عامة من الوثائق في Github لواجهات برمجة التطبيقات ونقاط النهاية الداخلية.
في البداية، نشرنا وثائقنا على Apiary، وهو أداة رائعة لنمذجة ونشر وثائق API. ومع ذلك، فإن تضمين Apiary في موقعنا لا يعمل على الأجهزة المحمولة، لذلك نستخدم الآن Jekyll لإنشاء وثائق ثابتة بدلاً من ذلك. وثائق SparkPost API الخاصة بنا الآن تُحمَل بسرعة وتعمل بشكل جيد على الأجهزة المحمولة، وهو أمر مهم للمطورين الذين لا يجلسون دائمًا أمام الكمبيوتر.
من المهم أن يكون لديك وثائق API دقيقة وقابلة للاستخدام لتجنب التغييرات المفاجئة، سواء كانت متعمدة أو غير متعمدة. قررنا استخدام نهج بسيط لوثائق API باستخدام لغة Markdown تُسمى API Blueprint و إدارة مستنداتنا في Github. يساهم مجتمعنا ويتحسن في هذه الوثائق المفتوحة المصدر. كما نحافظ على مجموعة غير عامة من الوثائق في Github لواجهات برمجة التطبيقات ونقاط النهاية الداخلية.
في البداية، نشرنا وثائقنا على Apiary، وهو أداة رائعة لنمذجة ونشر وثائق API. ومع ذلك، فإن تضمين Apiary في موقعنا لا يعمل على الأجهزة المحمولة، لذلك نستخدم الآن Jekyll لإنشاء وثائق ثابتة بدلاً من ذلك. وثائق SparkPost API الخاصة بنا الآن تُحمَل بسرعة وتعمل بشكل جيد على الأجهزة المحمولة، وهو أمر مهم للمطورين الذين لا يجلسون دائمًا أمام الكمبيوتر.
من المهم أن يكون لديك وثائق API دقيقة وقابلة للاستخدام لتجنب التغييرات المفاجئة، سواء كانت متعمدة أو غير متعمدة. قررنا استخدام نهج بسيط لوثائق API باستخدام لغة Markdown تُسمى API Blueprint و إدارة مستنداتنا في Github. يساهم مجتمعنا ويتحسن في هذه الوثائق المفتوحة المصدر. كما نحافظ على مجموعة غير عامة من الوثائق في Github لواجهات برمجة التطبيقات ونقاط النهاية الداخلية.
في البداية، نشرنا وثائقنا على Apiary، وهو أداة رائعة لنمذجة ونشر وثائق API. ومع ذلك، فإن تضمين Apiary في موقعنا لا يعمل على الأجهزة المحمولة، لذلك نستخدم الآن Jekyll لإنشاء وثائق ثابتة بدلاً من ذلك. وثائق SparkPost API الخاصة بنا الآن تُحمَل بسرعة وتعمل بشكل جيد على الأجهزة المحمولة، وهو أمر مهم للمطورين الذين لا يجلسون دائمًا أمام الكمبيوتر.
فصل النشر عن الإصدار
تعلمنا في وقت مبكر الحيلة القيمة لفصل النشر عن الإصدار. بهذه الطريقة، يمكننا نشر التغييرات بشكل متكرر عندما تكون جاهزة من خلال التسليم والنشر المستمر، لكننا لا نعلن عنها أو نوثقها علنًا في نفس الوقت. ليس من غير المألوف أن نقوم بنشر نقطة نهاية API جديدة أو تحسين لنقطة نهاية API موجودة واستخدامها من داخل واجهة المستخدم أو مع الأدوات الداخلية قبل أن نوثقها وندعمها علنًا. بهذه الطريقة، يمكننا إجراء بعض التعديلات عليها من أجل قابلية الاستخدام أو الالتزام بالمعايير دون القلق بشأن إجراء تغيير مروع. بمجرد أن نكون راضين عن التغيير، نضيفه إلى توثيقنا العام.
تعلمنا في وقت مبكر الحيلة القيمة لفصل النشر عن الإصدار. بهذه الطريقة، يمكننا نشر التغييرات بشكل متكرر عندما تكون جاهزة من خلال التسليم والنشر المستمر، لكننا لا نعلن عنها أو نوثقها علنًا في نفس الوقت. ليس من غير المألوف أن نقوم بنشر نقطة نهاية API جديدة أو تحسين لنقطة نهاية API موجودة واستخدامها من داخل واجهة المستخدم أو مع الأدوات الداخلية قبل أن نوثقها وندعمها علنًا. بهذه الطريقة، يمكننا إجراء بعض التعديلات عليها من أجل قابلية الاستخدام أو الالتزام بالمعايير دون القلق بشأن إجراء تغيير مروع. بمجرد أن نكون راضين عن التغيير، نضيفه إلى توثيقنا العام.
تعلمنا في وقت مبكر الحيلة القيمة لفصل النشر عن الإصدار. بهذه الطريقة، يمكننا نشر التغييرات بشكل متكرر عندما تكون جاهزة من خلال التسليم والنشر المستمر، لكننا لا نعلن عنها أو نوثقها علنًا في نفس الوقت. ليس من غير المألوف أن نقوم بنشر نقطة نهاية API جديدة أو تحسين لنقطة نهاية API موجودة واستخدامها من داخل واجهة المستخدم أو مع الأدوات الداخلية قبل أن نوثقها وندعمها علنًا. بهذه الطريقة، يمكننا إجراء بعض التعديلات عليها من أجل قابلية الاستخدام أو الالتزام بالمعايير دون القلق بشأن إجراء تغيير مروع. بمجرد أن نكون راضين عن التغيير، نضيفه إلى توثيقنا العام.
