أبي إصدار استراتيجية

أربعة ريست أبي إصدارات استراتيجيات.

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

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

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

عديمي الجنسية: لا يحتفظ بسياق العميل بين الطلبات القابلة للتخزين المؤقت: يعتمد على قواعد التخزين المؤقت هتب العميل / الخادم المنحى: يفصل المخاوف بين العملاء والخوادم الطبقات: يستفيد نظام الطبقات وواجهة موحدة.

أربعة ريست أبي المشتركة استراتيجيات الإصدار.

هناك أربع طرق شائعة لإصدار أبي ريست.

1. الإصدار من خلال مسار أوري.

طريقة واحدة لإصدار واجهة برمجة تطبيقات ريست هي تضمين رقم الإصدار في مسار عنوان ورل.

يتم استخدام هذه الاستراتيجية من قبل زماترز وكذلك شركات أخرى مثل الفيسبوك، تويتر، إيربنب، وغيرها.

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

يبدو الإصدار الداخلي من واجهة برمجة التطبيقات كما يلي:

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

إصدارات صغيرة وتصحيحات: هذه شفافة للعميل وتستخدم داخليا للتحديثات المتوافقة مع الإصدارات السابقة. وعادة ما يتم إبلاغهم في سجلات التغيير لإعلام العملاء عن وظيفة جديدة أو إصلاح الأخطاء.

هذا الحل لديه بصمة كبيرة جدا في قاعدة التعليمات البرمجية كما إدخال تغييرات كسر يعني متفرعة أبي بأكمله.

2. الإصدار من خلال معلمات الاستعلام.

هناك خيار آخر لإصدار واجهة برمجة تطبيقات ريست هو تضمين رقم الإصدار كمعلمة طلب بحث.

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

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

3. فيرسيونينغ من خلال رؤوس مخصصة.

يمكن أيضا إصدار واجهات برمجة التطبيقات ريست من خلال توفير رؤوس مخصصة مع رقم الإصدار المضمنة كخاصية.

والفرق الرئيسي بين هذا النهج والاثنين السابقين هو أنه لا فوضى أوري مع معلومات الإصدار.

4. الإصدار من خلال التفاوض المحتوى.

كورل - H & # 8220؛ أسيبت: أبليكاتيون / vnd. xm. device + جسون؛ فيرسيون = 1 & # 8221؛ مثال / المعهد / المنتجات.

وتتمثل آخر إستراتيجية نخاطبها في عملية الإصدار من خلال التفاوض على المحتوى.

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

واحدة من عيوب هذا النهج هو أنه يمكن الوصول إليها أقل من واجهات برمجة التطبيقات التي تم إصدارها من قبل أوري: إن طلب رؤوس هتب مع أنواع الوسائط يجعل من الصعب اختبار واستكشاف واجهة برمجة التطبيقات باستخدام متصفح.

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

أي أفكار أو توصيات؟ ترك تعليق أدناه!

ورقة بيضاء مجانية: تعرف على ستاندارد + كيس.

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

هل نحن بحاجة لجعل باكجينغ (مجلد) وفقا للنسخة الرئيسية؟

سؤال آخر هو، كيف يتطلب إصدار المخطط إذا تغيير أبي تغيير في جداول قاعدة البيانات. أي رابط؟

شيء واحد غير موثقة في كثير من الأحيان هو كيفية إدارة التعليمات البرمجية وجميع الإصدارات التي تدعمها أبي.

أنا & # 8217؛ م المهتمة للعثور على نمط جيد لإدارة التعليمات البرمجية وتجنب الكابوس الإصدار.

بلدي تنفيذ النهج 3 لربيع-ويبفك:

قد تكون أيضا مهتما ب.

كيف اخترقنا تجربة إيربنب مع أت & # 038؛ T و هب و إنتيل.

جديد سيرفيسينو التكامل يقلل الوقت لحل.

موغسوفت و زماترز التكامل يأخذ إدارة الحوادث إلى مستوى جديد.

غيبوبة جوبز كان & # 8217؛ ر توقف عن طريق البريد الإلكتروني البث.

بحاجة إلى دعم؟

لدينا موقع المجتمع مخصص هو أفضل مكان للحصول على مساعدة على جميع المنتجات زماترز. لدينا فريق من الموظفين دعم الخبراء والمستخدمين داخل مجتمعنا يمكن أن تساعدك على الحصول على الجواب الصحيح.

إصدار أبي الخاص بك هو الخطأ، وهذا هو السبب قررت أن تفعل ذلك 3 طرق خاطئة مختلفة.

في النهاية، قررت أعدل، كانت الطريقة الأكثر توازنا هو شخ الجميع قبالة على قدم المساواة. بالطبع أنا & # x2019؛ م يتحدث عن إصدار أبي وليس منذ كبيرة & # x201C؛ علامات التبويب مقابل المساحات & # x201D؛ النقاش رأيت الكثير من المعتقدات القوية في مخيمات مختلفة تماما.

كان هذا على ما يرام. عندما بنيت هل أنا بوند؟ (هيب) في أواخر نوفمبر، كان المقصود أن تكون خدمة بسيطة وسريعة أن بعض الناس سوف تستخدم. وأعتقد أنه من العادل أن نقول إن النقطتين الأوليين قد تحققت، ولكن ليست الأخيرة. لم يكن & # x2019؛ t & # x201C؛ عدد قليل & # x201D؛، في الواقع بنهاية الأسبوع الأول كان أكثر من غوغل أناليتيكش يمكن التعامل معها. النقطة هي أنه يمكنك & # x2019؛ t التنبؤ دائما المستقبل عند كتابة أبي الخاص بك، وفي مرحلة ما قد تحتاج إلى تغيير شيء أن الناس بالفعل تعتمد على.

ولكن هنا & # x2019؛ s المشكلة & # x2018؛ في كل مرة تبدأ فيها الحديث عن أي شيء يتعلق بواجهات برمجة التطبيقات عبر هتب، يحدث ذلك:

كل الطريقة التي تقوم بدورها هناك فلسفية مختلفة تأخذ على & # x201C؛ الطريق الصحيح & # x201d؛ والكثير من الوراء وإلى الأمام على ريست، ما هو ريستفول، ما هو ليس وإذا كان الأمر كذلك. دعنا نتحدث عن تغييرات واجهة برمجة التطبيقات، والتأثير على إصدار الإصدارات، ولماذا يوجد الكثير من الأفكار المتباينة حول كيفية القيام بذلك، وفي النهاية، لماذا لا يكون أي من المتبرع مهما بنفس القدر من الأهمية في إنجاز المهام.

سحب المزيد من البيانات الخرق.

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

لماذا ا؟ لأن & # x201C؛ باتلفيلدرويز & # x201D؛ هو باسكال-كاسد وهو أمر رائع لمطابقته مع الطبقات كس مرمزة (على الرغم من أنه ربما ليس نهجا جيدا على المدى الطويل) ولها & # x201C؛ مستقرة & # x201D؛ اسمه للإشارة إلى (لقد فشلت & # x2019؛ تغييره، حتى لو كان هناك & # x2019؛ s خرق الثاني)، ولكن هذا & # x2019؛ s غير مناسبة للعرض كعنوان. كل هذا يأتي من أزور الجدول التخزين وأنا ثم انتقل إلى سكل أزور لسحب البيانات العلائقية التي تصف فعلا الخرق. واحدة من السمات في هذا التخزين العلائقية هو الاسم الذي تراه أعلاه.

ما أردت حقا القيام به هو شيء أشبه بهذا:

احصل عليه؟ إلى النقطة السابقة على اسم الخرق، هذا & # x2019؛ ق لا يزال هناك في السمة اسم ولكن الآن لدينا عنوان كذلك. هذا ما تظهره للأشخاص & # x2018؛ & # x201C؛ باتلفيلد هيروز & # x201D؛ & # x2018؛ ولكن الأهم من ذلك، إذا بوكر هو بوند مرة أخرى أستطيع أن أذكر خرق شيء مثل Gawker2018 وعنوان يمكن أن يكون شيئا ودية على غرار & # x201C؛ قاذف (الجيش السوري هجوم الكتروني) & # x201D؛. وهو يقسم ما هو مستقر ويمكن التنبؤ به من ذلك الذي لا يعني أنه يمكن للأشخاص إنشاء تبعيات مثل الصور أو الأصول الأخرى على السمة نيم.

يجب أن تكون البيانات الأخرى واضحة جدا: تاريخ الإخلال، عندما تمت إضافته إلى النظام، عدد الحسابات التي تم تحديدها، ووصف الخرق (مرة أخرى، قد يتغير هذا إذا كان يجب تعديل النص) و # x201C؛ DataClasses & # x201D؛. واحدة من الأشياء التي كان كثير من الناس قد طلب هو وصف ما تم اختراقه في الخرق لذلك هناك الآن مجموعة كاملة من الصفات من يمكن أن تضاف عن طريق مجموعة على الخرق نفسه. I & # x2019؛ م تظهر بالفعل هذه تحت كل خرق على صفحة المواقع بوند (وهذا هو سبب آخر أنا قد الآن قرص بعض من الأوصاف).

هذا هو تغيير كسر. في حين أن مشاعر أبي هي نفسها & # x2018؛ تقديم اسم حساب، نعود قائمة من الانتهاكات & # x2018؛ لم يعد هناك مجموعة من أسماء الخرق. إذا أنا ببساطة استبدال أبي القديم مع هذا واحد، الاشياء سوف كسر. واجهات برمجة التطبيقات. يجب. تتطور.

تتطور البرامج، يجب أن يتم إصدار واجهات برمجة التطبيقات.

اسمحوا & # x2019؛ ق فقط تكون واضحة وضوح الشمس حول هذا: العالم يتحرك جرا. استمر أبي ل هيب حوالي 2 أشهر، وليس لأنه تم تصميم سيئة ولكن لأن الخدمة أصبحت بعنف، ناجحة بشكل غير متوقع. أنا أحب هذه الأنواع من المشاكل، وذلك ينبغي لك.

الآن كان لي خيار؛ إما أن أستطيع أن أفعل ما كان لي وحرمان الناس من أفضل طريقة، وأنا يمكن أن تضيف إلى الخدمة الحالية بطريقة غير كسر أو أنا يمكن أن تخلق نسخة جديدة (وإن تعريض نفس الكيان بطريقة مختلفة) وبناء انها أفضل طريقة لعنة كنت أعرف كيف. لا بايت لا لزوم لها، على غرار بشكل صحيح (حتى أقرر إصدار جديد هو أكثر صحة) وتمثيل جيد للكيان الذي أنا & # x2019؛ م في نهاية المطاف محاولة للوصول الى المستهلكين & # x2019؛ التطبيقات.

ليس هناك شيء خاطئ في تقديم نسخة جديدة من أبي عندما يكون الشيء الأكثر منطقية القيام به. بكل الوسائل، هل دامنديست للحصول عليه & # x201C؛ الحق & # x201D؛ من اليوم الأول، ولكن فعل ذلك مع توقع أن & # x201C؛ يمين & # x201D؛ هي حالة مؤقتة. هذا هو السبب في أننا بحاجة إلى أن تكون قادرة على الإصدار.

مختلف مخيمات الإصدار.

الحق، فكيف يمكن أن يكون هذا الإصدار الأعمال يكون؟ أعني أنه ينبغي أن يكون ممارسة بسيطة، أليس كذلك؟ والمشكلة هي أنه يحصل على فلسفية جدا، ولكن بدلا من الحصول على تعثر في ذلك الآن، واسمحوا لي أن الخطوط العريضة للمدارس الثلاث المشتركة من الفكر من حيث كيف أنها & # x2019؛ نفذت عمليا:

ورل: يمكنك ببساطة إزاحة إصدار واجهة برمجة التطبيقات في عنوان ورل، على سبيل المثال: هتبس: // هافيبينبوند / أبي / v2 / برياكثداكونت / فو رأس طلب مخصص: يمكنك استخدام عنوان ورل نفسه كما كان من قبل، ولكن أضف رأسا مثل & # x201C؛ أبي - version: 2 & # x201D؛ قبول الرأس: يمكنك تعديل رأس قبول لتحديد الإصدار، على سبيل المثال & # x201C؛ قبول: أبليكاتيون / vnd. haveibeenpwned. v2 + جسون & # x201D؛

كانت هناك العديد من الأشياء المكتوبة على هذا و أنا & # x2019؛ م الذهاب إلى ربط لهم في نهاية المشاركة، ولكن هنا & # x2019؛ ق نسخة مختصرة:

تمتص عناوين ورل لأنها يجب أن تمثل الكيان: إنني أتفق فعلا مع هذا ما أن الكيان I & # x2019؛ استرجاع هو حساب خرق، وليس نسخة من حساب خرق. من الناحية الدلالية، فإنه & # x2019؛ s ليس صحيحا حقا ولكن اللعنة عليه & # x2019؛ ق سهلة الاستخدام! تمتص رؤوس الطلبات المخصصة لأنها ليست طريقة دلالية لوصف المورد: توفر لنا مواصفات هتب وسيلة لطلب الطبيعة التي نمثلها مثل المورد الذي يتم تمثيله عن طريق رأس القبول، ولماذا تتكاثر هذه؟ قبول الرؤوس تمتص لأنه يصعب اختبارها: لم يعد بإمكاني إعطاء عنوان ورل لشخص ما سوى & # x201C؛ هنا، انقر على هذا & # x201D؛، بدلا من ذلك يجب إنشاء الطلب بعناية وتهيئة رأس القبول بشكل مناسب .

تميل الحجج المختلفة لكل نهج ومعارضته إلى الانتقال من & # x201C؛ هذا هو & # x2018؛ يمين & # x2019؛ طريقة للقيام بذلك ولكن هو أقل عملية & # x201D؛ من خلال إلى & # x201C؛ هذه هي أسهل طريقة لإنشاء شيء مستهلك مما يجعله & # x2018؛ يمين & # x2019؛ & # x201D ؛. هناك الكثير من النقاش حول الوسائط الفائقة، والتفاوض على المحتوى، وما هو & # x201C؛ ريست & # x201D؛ وجميع المسائل الأخرى. للأسف هذا غالبا ما يحصل الفلسفية ويفقد البصر ما يجب أن يكون الهدف الحقيقي: بناء البرمجيات التي تعمل ولا سيما لأبي، مما يجعلها قابلة للاستهلاك بسهولة.

و & # x2019؛ ق عن وجود عقد مستقر، غبي!

أكثر أهمية من كل الهتاف والهذيان حول القيام بذلك بهذه الطريقة أو بهذه الطريقة هو إعطاء الناس الاستقرار. إذا كانوا يستثمرون جهدهم كسب جهدهم كتابة التعليمات البرمجية لاستهلاك أبي الخاص بك ثم كنت & # x2019؛ د أفضل لعنة جيدا لا تذهب وكسرها على مزيد من أسفل الخط.

بصراحة، المناقشات حول ما هو & # x201C؛ ريستفول & # x201D؛ مقابل ما ليس كما لو أن المصطلح نفسه سوف تملي نجاحك هو مجرد المكسرات. تحويل هذه المناقشة إلى & # x201C؛ وفيما يلي الأسباب العملية التي تجعل هذا الأمر منطقيا وهذا هو ما قد يحدث إذا لم تجر ذلك & # x201D؛ و & # x2019؛ جميع الأذنين. المشكلة هي، حتى أصوات العقل في المناقشات الصاخبة ترك الشك فيما هو حقا أفضل نهج، وبالتالي أنا & # x2019؛ وصلت إلى حل وسط & # x2026؛

وهنا 3 طرق خاطئة للاستهلاك هيب أبي يمكنك الآن اختيار من بينها.

حسنا، والآن بعد أن أنشأنا & # x2019؛ ولكن بوضوح أنك تفعل ذلك خطأ، أنا & # x2019؛ d أود أن أعطيك الخيار للاختيار من بينها أي واحدة من 3 طرق خاطئة. انتظر & # x2018؛ ماذا؟! هذا & # x2019؛ ق مثل هذا: ومع ذلك أنا تنفيذ أبي، فإنه إما أن يكون من الصعب جدا أن تستهلك، أكاديمية جدا، من المرجح جدا أن تفشل في وكيل أو شيء جدا شيء. بدلا من اختيار 1 طريقة خاطئة، وأنا & # x2019؛ قررت أن أعطيك كل 3 طرق خاطئة ويمكنك اختيار واحد الذي هو أقل خطأ بالنسبة لك.

طريقة خاطئة 2 - رأس طلب مخصص:

حتما، شخص ما يقول لي أن توفير 3 طرق خاطئة هو شيء خاطئ القيام به. فاز & # x2019؛ t يعني المزيد من كود كودج للحفاظ على؟ لا، يعني ببساطة أن تطبيق ويب أبي الأساسي مزين بخاصيتين:

أول واحد هو مجرد قيود التوجيه التي تنفذ روتفاكتوريواتريبوت. أنا تمرير في الطريق وتمرير في النسخة التي يمكن تعيين إلى ذلك الطريق ثم تنفيذ يبحث عن وجود إما & # x201C؛ أبي الإصدار و # x201D. رأس أو رأس قبول يتطابق مع هذا النمط:

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

السمة الثانية تزيين طريقة GetV2 أعلاه يأتي من باب المجاملة من أبي ويب 2 وميزة توجيه السمة. بالطبع يمكننا أن نفعل دائما التوجيه في أبي ويب ولكن كان عادة ما تعرف على الصعيد العالمي. توجيه السمة من هذا القبيل يجلب تعريف المسار إلى السياق الذي يتم تطبيقه ويجعل من القتلى من السهل أن نرى ما هو عمل وحدة تحكم سيتم استدعاؤها عن طريق ما الطريق. وهذا يعني أيضا أن تطبيقات لجميع 3 طرق خاطئة للاتصال أبي الجلوس معا في مكان واحد أنيق.

لذلك باختصار، لا، هذا لا & # x2019؛ ر خلق الكثير من كلودج وسهلة جدا للحفاظ على. ستعيد كل واحدة من المقاربات الثلاثة نفس النتيجة بالضبط والأهم من ذلك، أنها ستظل مستقرة ولن تتغير بأي طريقة كسر، وفي نهاية المطاف، فإن هذا هو الأكثر & # x2019؛ s الشيء المهم بغض النظر عن الخيار الذي تختاره. التنفيذ الكامل الآن أيضا موثقة بشكل واضح على صفحة أبي للموقع.

ولكن ماذا لو لم يتم تحديد إصدار؟

أنت تعرف بت حيث قلت يمكنك & # x2019؛ ر كسر ما & # x2019؛ s بالفعل هناك؟ نعم، وهذا يعني أنه إذا كنت تفعل ما تفعله الآن & # x2018؛ عدم تحديد إصدار & # x2018؛ ثم تحصل على ما تحصل عليه الآن. وبعبارة أخرى، لا يوجد طلب للحصول على إصدار محدد يعني أنك تحصل على الإصدار 1.

أنا & # x2019؛ م موافق تماما مع ذلك بغض النظر عن أن وصلت إلى هذه النقطة بشكل افتراضي. أنا أعرف بعض الناس دائما ترغب في العودة إلى أحدث إصدار إذا كان عدد إيسن & # x2019؛ ر المحدد، ولكن إمهو الذي يكسر كله & # x201C؛ عقد مستقر & # x201D؛ هدف؛ ما تحصل عليه من أبي اليوم قد تكون مختلفة تماما عن ما تحصل غدا إذا أنا تنقيحها. هذا من شأنه أن تمتص وسوف كسر الأشياء.

لديك 3 خيارات، ولكن تفضيلي الشخصي هو & # x2026؛

لدي ترف السيطرة على كل من أبي والمستهلك الرئيسي من كونها هيب الموقع نفسه. وبالنظر إلى I & # x2019؛ لقد قدمنا ​​3 خيارات لاستهلاك واجهة برمجة التطبيقات، أي واحد يمكنني استخدام نفسي؟

أنا & # x2019؛ ذهب مع المفضلة الفلسفية التي هي لتحديد ذلك عن طريق رأس قبول. لا أظن أن هذا صحيح، والبعض الآخر خاطئ، بل أعتقد أن هذا يجعل الأمر أكثر منطقية لسببين رئيسيين:

أوافق على أن عنوان ورل يجب ألا يتغير: إذا وافقنا على أن عنوان ورل يمثل المورد ثم ما لم نحاول & # x2019؛ تمثيل إصدارات مختلفة من المورد نفسه، لا، لا أريد تغيير عنوان ورل. خرق فو هي دائما خرق فو وأنا لا & # x2019؛ ر أعتقد أن فقط لأنني تغيير البيانات التي تم إرجاعها عن فو أن موقع فو يجب أن تتغير. أوافق على أن قبول الرؤوس يصف كيف تريد & # x2019؛ d مثل البيانات: هذا هو دلالة من مواصفات هتب وكما أن الدلالات الدلالية لأفعال الطلب تجعل الكثير من المعنى (أي أننا نحصل على أو نضع أو حذف أو نشر) وكذلك الطريقة التي يرغب العميل في تمثيل المحتوى.

لا يعني هذا بأي حال من الأحوال أن أعتقد أن الاثنين الآخرين خاطئون وبصراحة، لا توجد طريقة أفضل لتبادل أبي مع شخص ما من القول & # x201C؛ هنا، انقر فوق هذا & # x201D؛، ولكن عندما أستطيع بسهولة بناء الطلب وإدارة رؤوس، وأنا & # x2019؛ ذهب مع هذا الطريق.

في الواقع، وتأتي للتفكير في ذلك، وأنا أيضا استخدام الإصدار في مسار المجال. لماذا ا؟ فقط من خلال عملية كتابة هذا أبي كنت باستمرار التواصل مع الناس حول طرق الاستعلام عنه (أكثر على ذلك في وقت لاحق) والسمات التي يعود. أن تكون قادرا على الذهاب نفض الغبار على البريد الإلكتروني ويقول & # x201C؛ مهلا، هنا & # x2019؛ ق ما & # x2019؛ م التفكير & # x201D؛ وأنها ببساطة انقر عليه والحصول على نتائج لا تقدر بثمن. هذه هي النقطة التي يقترحها أنصار إصدار عناوين ورل بشكل صحيح: لا يمكنك ببساطة إجراء ذلك عندما تكون & # x2019؛ تعتمد على الرؤوس.

أوه، وفي حال كنت & # x2019؛ إعادة فحص لي، في وقت كتابة هذا أنا لم أكن & # x2019؛ ر توالت بعد الموقع إلى v2 من أبي. الآن بعد أن يتم سحب البيانات الخرق مرة أخرى في أبي عندما يحدث بحث فهذا يعني أن لدي ترف عدم تحميل جميع الخروقات في المصدر على تحميل الأولي (التي لم تكن أبدا أن تكون مستدامة مع مجموعة البيانات توسع). هذا & # x2019؛ ليرة لبنانية حفظ مجموعة من حركة المرور الصادرة وتسريع الأمور بالنسبة للأشخاص من حيث الحصول على تحميل الموقع، ولكنه يعني أيضا مجرد المزيد من العمل قليلا على نهايتي. ترّقب.

في الختام.

من الواضح أنني & # x2019؛ لقد كان قليلا اللسان في الخد هنا فيما يتعلق كل شيء يجري الخطأ ولكن بصراحة، وكلما قرأت على هذا والمزيد من الأسئلة التي تسأل، وأكثر خطأ كل طريق يبدو بطريقة أو بأخرى. في الواقع أنا أعرف لعنة جيدا أن هناك جوانب من بلدي التنفيذ التي ستشار إليها باسم & # x201C؛ خطأ & # x201D؛ (أستطيع أن أفكر في اثنين على الأقل) وبطبيعة الحال أنا & # x2019؛ م تستعد للهجوم المحتمل من ردود الفعل في هذا الشأن. والشيء هو على الرغم من كل من هذه الخيارات يعمل وبصراحة، لجميع الأغراض العملية، فإنها تعمل تماما وكذلك بعضها البعض.

إذا كنت قد أترك الآخرين يفكرون في كيفية إصدار واجهات برمجة التطبيقات (أبيس) الخاصة بهم بفكر نهائي: لن يستخدم أي شخص واجهة برمجة التطبيقات (أبي) إلا بعد إنشائه. وقف المماطلة. لا شيء من هذه & # x201C؛ سيئ & # x201D؛ في أي معنى ملموس، أنها & # x2019؛ إعادة مختلفة فقط. أنها كلها قابلة للاستهلاك بسهولة، فإنها جميعا عودة نفس النتيجة وليس من بينها من المرجح أن يكون لها أي تأثير حقيقي على نجاح المشروع الخاص بك.

المراجع.

تجاوز المكدس: أفضل الممارسات لإصدار أبي؟ (سؤال كبير، إجابات كبيرة، أغلقت كما & # x201c؛ غير بناء & # x201d؛، أفترض لأن & # x201c؛ بيل سحلية و # x201d؛ خرجت على الجانب الخطأ من السرير ذلك الصباح) ليكسيكال سكوب بلوغ: هاو أر ريست تم إصدار واجهات برمجة التطبيقات؟ (مقارنة جيدة بين ممارسات الإصدار عبر الخدمات، وإن كان ذلك الآن عامين من العمر) كوديبلكس: نموذج قيود التوجيه (مرتبط في صفحة ويب أبي ل ميكروسوفت & # x2019؛ كمثال على إصدار واجهات برمجة التطبيقات عن طريق إضافة رأس مخصص) كودبيتر: فيرسيونينغ ريستفول الخدمات (واقعية جدا ووصف جيد للطرق المختلفة التي قد تتغير بها واجهة برمجة التطبيقات) مدونة فيناي ساهني & # x2019: أفضل الممارسات لتصميم واجهة برمجة تطبيقات ريستفول براغماتية (هو & # x2019؛ s؛ ريسولتينغ فور ورل فيرسيونينغ فور إنديا & # x201C ؛ استكشاف المستكشف & # x201D؛) المحورية لانس: إصدار أبي (عرض جيد للآراء المتضاربة هناك) ويب كومة من الحب: أسب ويب أبي الإصدار مع أنواع وسائل الإعلام (جيد نهاية إلى نهاية تجول من إنشاء التطبيق لدعم الإصدار من قبل التفاوض على المحتوى)

مرحبا، أنا & # x27؛ م تروي هانت، أكتب هذا بلوق، وخلق دورات ل بلورالزيت وأنا المدير الإقليمي مايكروسوفت و مفب الذي يسافر العالم يتحدث في الأحداث والمهنيين تكنولوجيا التدريب.

مرحبا، أنا & # x27؛ م تروي هانت، أكتب هذا بلوق، وخلق دورات ل بلورالزيت وأنا المدير الإقليمي مايكروسوفت و مفب الذي يسافر العالم يتحدث في الأحداث والمهنيين تكنولوجيا التدريب.

الأحداث القادمة.

أنا عادة تشغيل ورش خاصة حول هذه، وهنا الأحداث العامة القادمة سأكون على:

لم يكن لديك بلورالزيت بالفعل؟ ماذا عن التجربة المجانية لمدة 10 أيام؟ التي سوف تحصل على الوصول إلى الآلاف من الدورات من بينها العشرات من بلدي بما في ذلك:

"سحابة أبدا يذهب إلى أسفل"، أزور سلاز وغيرها من التوافه التوافر.

وهنا كيف اختراق بيل - حقن سكل ضربة تلو الأخرى.

إشترك الآن!

حقوق الطبع والنشر 2018، تروي هانت.

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

تنصل.

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

نشرت مع شبح.

هذا الموقع يعمل بشكل كامل على الشبح ويتم بفضل الدعم الكريمة. اقرأ المزيد عن سبب اختياري لاستخدام جوست.

ريستفول أبي إصدار رؤى.

عندما يتعلق الأمر الإصدار أبي هناك الكثير من أفضل الممارسات والرؤى ولكن لا يزال هناك لا الصخور الصلبة أفضل الممارسات.

من أجل فهم نسخة أبي مريحة نحن بحاجة أولا إلى فهم المشكلة.

مشكلة الإصدار.

واحد لا كسر العملاء.

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

لسوء الحظ، بغض النظر عن مدى ببراعة كنت مهندس الحل الخاص بك، قد تجد جيدا أنه، مع مرور الوقت، لديك لتغييره.

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

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

والآن بعد أن فهمنا المشكلة، ما هي الحلول الممكنة؟

4 الحلول الممكنة ل أبي الإصدار.

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

في هذه الطريقة يتم وضع النسخة صراحة جدا في أوري أبي. فمثلا:

. / مابس / فيرسيون / 2. / مابس / فيرسيون / 2 / بيلدينغز / فيرسيون / 3. / خرائط / V2 / المباني.

تظهر الخيارات أعلاه ثلاث طرق مختلفة لفضح الإصدارات من خلال عنوان ورل الخاص بك؛

أولا، نموذج كامل من الحبيبات الخشنة الحبيبية ثم طريقة أكثر موضوعا الحبيبات بدقة أكثر مما يتيح لنا القدرة على إصدار عناصر منفصلة من أبي (الطرق في هذه الحالة). يظهر الخيار الثالث فقط النموذج الأقل تعبيرا قليلا عن وجود وسيطة إصدار واحد (على سبيل المثال 'v2') بدون عقدة 'الإصدار' الصريحة في التسلسل الهرمي لعنوان ورل.

أنا شخصيا، لا أحب هذا النموذج. من وجهة نظر أنقى يقال أن أوري في ريست يجب أن تمثل بنية الموارد فقط.

إصدار ليس موردا هو سمة من الموارد.

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

يمكننا أن نرى بالفعل كيف يمكن أن ينظر إلى مزايا لشخص واحد على أنها عيوب لآخر.

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

2) رأس قبول.

يوجد رأس هتب معروف باسم "قبول" يتم إرساله بناء على طلب من عميل إلى خادم. على سبيل المثال.

هذا تدوين يقول أن أنا، العميل، أود أن يكون الرد في جسون من فضلك.

تستخدم رؤوس القبول هذا الرأس لتعويض أنواع الموارد الخاصة بك، على سبيل المثال:

قبول: تطبيق / vnd. myapi. v2 + جسون.

الآن؛ شنق على هنا لأن هذا هو بناء غريب قليلا وجدنا أنفسنا تبحث في لذلك دعونا المشي من خلال ذلك.

مواصفات الإنترنت تقول أنني، كمورد، يمكن أن تحدد (ويجب أن تسجل) نوع وسائل الإعلام. إذا كنت تفعل هذا فإنه يسمى (لا مفاجأة) نوع "بائع" وسائل الإعلام. يجب أن بادئة نوع بلدي مع 'فند' لجعلها واضحة انها التعريف الخاص بي. ثم يجب أن أقول ما هو اسم النوع الفعلي الذي أعرفه على سبيل المثال. 'ميابي'. ومع ذلك، فإن مواصفات لا شيء عن رقم الإصدار حتى الناس قد اتخذت لقول أن اسم نوع وسائل الإعلام الخاصة بهم يتضمن رقم الإصدار، على سبيل المثال:

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

يرجى ملاحظة أن هناك طريقة بديلة للقيام بذلك دون أي تسجيل مسبق من وسائل الإعلام من نوع استخدام x. كبادئة:

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

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

ومع ذلك يبدو أسهل بكثير لتمرير حول قبول: رأس فند مما هو لتمرير حول رؤوس طلب مخصص.

قبول الرؤوس تمتص لأنهم أصعب لاختبار - لم يعد بإمكاني مجرد إعطاء شخص ما ورل ويقول "هنا، اتبع هذا الرابط"، بدلا من أن بناء بعناية الطلب وتكوين رأس قبول بشكل مناسب.

3) رأس طلب مخصص.

في مواصفات هتب الأصلية، يمكنك تحديد أي رأس هتب قديم يعجبك في طلب العميل طالما أنك تم إصلاحه مسبقا باستخدام "X-" على سبيل المثال.

تغيرت المواصفات ويمكنك الاستمرار في تمرير أي رأس طلب قديم من خلال ولكن لا يجب أن تكون ثابتة مسبقا مع 'X-' بعد الآن على سبيل المثال.

وهذا يعني أنك يمكن أن تطلب من عملاء أبي الخاص بك لتمرير في شيء من هذا القبيل.

لا ينصح باستخدام هذا الخيار ولا يستخدم كثيرا بسبب الأسباب التالية:

بعض أجهزة التوجيه (على الرغم من أن اليوم الأشياء مختلفة ومعظمهم سوف تمر على جميع الرؤوس) يمكن إما رفض طلب هتب كله أو مجرد عدم تمرير رأس خاص. تصحيح هذا قد يكون من الصعب جدا القيام به. كان لي التغيير لمواجهة مثل هذا الشيء حيث كانت بعض آلات الاتصال من خلال أجهزة التوجيه المختلفة وجهاز توجيه واحد واحد قد تم تكوينها لإزالة أنواع رأس غير قياسي. سمحت الرسالة من خلال - بما في ذلك جميع الرؤوس الأخرى - ولكن فقط بصمت إزالة تلك التي لم تعجب!

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

رؤوس طلبات مخصصة تمتص لأنها ليست حقا طريقة دلالية لوصف المورد - مواصفات هتب تعطينا وسيلة لطلب طبيعة نود المورد ممثلة في طريق رأس قبول، لماذا إعادة إنتاج هذا؟

4) معلمة أوري.

وهنا من الواضح أنني لا أرى العديد من الناس باستخدام:

ويستخدم هذا الأسلوب للغاية من قبل الأمازون، وجوجل و نيتفليكس ولكن لا يزال أنها ليست شعبية جدا. همم - ربما هناك شيء لذلك؟!

التفكير في الإصدار من يوم واحد.

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

إذا كنت مطورا رشيقة ثم هل يمكن أن يصرخ على الشاشة الآن.

رشيقة هو كل شيء عن اليوم. في الواقع، فإنه يقول على وجه التحديد - لا رمز للأشياء التي ليست في المواصفات. ومع ذلك، دعونا نكون واضحين: الترميز للتمدد ليست هي نفسها كما وضعت فعلا في ملحقات أنفسهم - وهو ما تتحدث عنه منهجية رشيقة.

ترك غرفة للإصدارات المستقبلية يناسب رشيقة على ما يرام.

إصدار أبي من الصعب!

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

حاول السماح بالتمدد في الشفرة من اليوم الأول.

فيما يتعلق بكيفية تحديد النسخة - إذا كان لديك اتفاقية إصدار في الاعتبار ثم تأكد من أن البنية التحتية الخاصة بك يمكن التعامل معها.

قراءة المزيد من المشاركات بواسطة هذا المؤلف.

شارك هذا المنشور.

الاشتراك في ريست أبي وما بعدها.

احصل على آخر المشاركات التي تم تسليمها مباشرة إلى بريدك الوارد.

أو الاشتراك عبر رسس مع فيدلي!

ريستفول أبي باسيك غدلينس.

لقد بدأ نموذج البيانات في تحقيق الاستقرار وكنت في وضع يسمح لك بإنشاء واجهة برمجة تطبيقات عامة ل & هيليب؛

ريست أبي مقابل إدارة خدمات ويب سواب.

Back in the day Web Services were the de facto standard for accessing "systems of record". SOAP web services…

API Expertise.

One of the most frequent questions I receive during API training and coaching engagements involves versioning. When to version. How to version. Whether to version at all. While not all APIs are exactly the same, I have found that there are certain patterns and practices that work for most team. I have pulled these together to provide a recommendation for a versioning strategy that will help most API providers – whether they are deploying internal, private APIs or public APIs outside the organization.

Do you really need to version your API?

APIs are contracts established between you and your API consumers. Ideally, you will never have to break this contract. This includes URI patterns, payload structures, field and parameter names, expected behavior, and everything else in between. The biggest benefit of this approach is obvious: An API consumer’s understanding never expires. Applications continue to work, making your consumers happy.

However, that may not be reality. There may be times when you need to make a breaking change. When this happens, you need to ensure that you never do anything that will cause your API consumers to fix code.

Breaking vs. non-breaking changes.

Non-breaking changes tend to be additive: adding new fields or nested resources to your resource representations, adding new endpoints such as a PUT or PATCH that was previously unavailable. API consumers should build client code that is resilient to these kinds of non-breaking changes.

Breaking changes include:

Renaming fields and/or resource paths – often for clarity after your API is released Changing payload structures to accommodate the following: renaming or removing fields (even if they are considered optional – contracts!); changing fields from a single value to a one-to-many relationship (e. g. moving from one email address per account to a list of email addresses for an account) Fixing poor choices of HTTP verbs, response codes, or inconsistent design across your API endpoints.

In short, once you release your API into the wild, you have to live with it. If you encounter one or more of the items above, it may be time to version your API to prevent breaking your existing API consumers.

Defining Your API versioning strategy.

Any evolving, growing API will require an API versioning strategy. When and how you version may vary based on the expectations of your API consumers. I generally recommend the following API versioning strategy as part of an overall API governance model:

If your API is in an early preview release, perhaps to gain feedback from consumers, establish proper expectations that your API may change. At this stage, you will remain at version 1 for some time but your API design may change. Things are volatile as a consumer, so they should expect that changes may occur Once released, your API should be considered a contract and cannot be broken without a new version release API versions are major. minor, following the general principles of semantic versioning Non-breaking changes result in a bump in the minor version; clients are automatically migrated to the latest verison and should not experience any negative side-effects Breaking changes result in a new major version; clients must specifically migrate to this new version as it contains one or more breaking changes. You must establish an appropriate timeline and regular communication with your API consumers to ensure that they migrate to the new version. In some cases, this may not be possible and your team will be required to support the previous API version indefinitely.

How to implement API versioning.

Once you determine that you need a new version of your API, you need to decide how to handle it. Preferrably, you have decided ahead of time and encouraged API consumers to request version 1 of your API. There are three common approaches to implement API versioning:

Resource versioning: the version is part of the Accept header in the HTTP request. مثلا Accept: application/vnd. github. v3+json is sent to GET /customers . This considered the preferred form of versioning by many, as the resource representations are versioned while keeping resource URIs the same. Some APIs choose to provide the latest version as the default, if not provided in the Accept header URI versioning: the version is part of the URI, either as a prefix or suffix. مثلا /v1/customers or /customers/v1 . While URI-versioning isn’t as pure as content-based versioning, it tends to be the most common as it works across a variety of tools that may not support customized headers. The downside is that resource URIs change with each new version, which some consider counter to the intent of having a URI that never changes. Hostname versioning: the version is part of the hostname rather than the URI. مثلا https://v2.api. myapp/customers . This approach is used when technology limitations prevent routing to the proper backend version of the API based on the URI or Accept header.

No matter which option you choose, API versions should only include the major number. Minor numbers should not be required (e. g. /v1/customers , not /v1.1/customers ).

افكار اخيرة.

Remember, APIs are contracts with your consumers. Break your contract and a new version is required. Choose a strategy, have a plan, and communicate that plan with your API consumers. They will thank you for it.

منتجات.

القانونية.

Get started instantly with Tyk SaaS. No credit card required, no trial period. Full access, generous quotas and FREE. Sign Up now.

هل لديك حساب؟ Click here to login to your account, or here to login to your dashboard.

Four strategies to version APIs and services.

Published on October 16, 2017.

To manage and maintain any runtime system, you need a comprehensive versioning strategy. Without a clear strategy in place, how do you know which services and APIs are deployed and which version to use? This article highlights four strategies to help you manage API and service interfaces and implementations. It also presents the advantages and disadvantages for each strategy.

The importance of versioning.

When you define a versioning strategy, you focus on your requirements for the following two key areas:

Service or API interface: When you change the interface, your users will need to change their code. Therefore, you must have a way to track and communicate to API and service consumers that they must change the version of their API or service interface. Service or API implementation: Each time that you change the implementation, your users should be aware of the change but might not have to change their code. However, your operations team will need to track which implementation a service or API uses.

The minimum number of versions.

Version strategies often have a clear system for getting new versions into production, but with little to no regard for how to retire a service. Consider an example of a platform that runs for a few years. It might have 30 services, each with 20 different versions. Without a plan to retire a service, the platform can end up with a total of 600 instances for just one service.

“ For an API or service, keep no more than three of its most granular versions in production… ”

By coupling a sensible versioning strategy with your management system, such as IBM® API Connect, you can reduce the number of services. For an API or service, keep no more than three of its most granular versions in production for each combination of its higher-level versions. For example, if the versioning scheme is vX. Y, every X version can have only three Y values in production. For the scheme vX. X.Y, every X. X version can have only three Y values in production.

The three production versions at each level relate to the following states:

Live: New consumers must use this version. Superseded: New consumers can subscribe to this version in extenuating circumstances. Deprecated: New consumers must not use this version.

The following table shows an example of a list with the maximum number of versions that are deployed with a one-dot strategy.

Maximum number of versions for a one-dot strategy.

In this example, the maximum number of deployments is the number of dots plus one to the power of three.

Maximum number of deployments.

When a new version is ready for release, it cannot go live until the following requirements are met:

The existing deprecated version is retired. The superseded version becomes deprecated . The live version becomes superseded .

By using a good API management tool, such as API Connect, you can quickly determine which consumers are using each version. You must notify them when the service becomes deprecated or superseded. If they do not migrate to the latest version, they must understand that they risk breaking their application.

In the following strategies, each version has its own branch in the source code repository. These branches are called code streams .

One-dot strategy.

The one-dot strategy indicates the major version, followed by a dot, and then the minor version. This strategy has the following syntax:

Overview of a one-dot strategy.

This strategy has the following characteristics:

أنها بسيطة. It offers tight coupling between the interface and the implementation. It has two code streams for you to manage and support. Potentially nine instances are deployed. It does not highlight significant redesigns. It is unclear when a minor change affects an interface or implementation change.

Two-dot strategy.

The two-dot strategy indicates the major version, a dot, the minor version, a dot, and then the fix number. This strategy has the following syntax:

Overview of a two-dot strategy.

This strategy has the following characteristics:

At the Fix level, you can version a service without versioning the interface. All new deployments of the implementation increment the version even if the interface is not changed. It couples the interface and implementation version without tightly binding them. It has three code streams for you to manage and support. Potentially 27 instances are deployed if three versions per version level are deployed. It does not highlight when major redesigns occur, such as when many existing interfaces are redesigned. If significant rework is required, it is not apparent.

Three-dot strategy.

The three-dot strategy is similar to the Version, Release, Modification, and Fixpack (VRMF) strategy that is used in IBM product versioning. This strategy indicates the release version, a dot, the major version, a dot, the minor version, a dot, and then the fix version. This strategy has the following syntax:

Overview of a three-dot strategy.

This strategy has the following characteristics:

It offers more precision across versions. It can version a service without versioning the interface, which means you do not have to update any catalog or developer portals. It can couple the interface and implementation version without tightly binding them. It has four code streams to manage and support. Potentially 81 instances are deployed if three versions per version level are deployed. It highlights when major redesigns occur, such as when many existing interfaces are redesigned. If significant rework is required, it is not apparent.

Decoupled strategy.

The interface and implementation are versioned independently. In this strategy, both the interface and the implementation follow a one-dot strategy. However, they can follow a more complex strategy, such as a two-dot or three-dot strategy.

This strategy has the following characteristics:

It has two code repositories with two streams in each repository. It hides the implementation version from the user. The implementation and interface have a complete disconnect. Developers and designers must align on the same strategy but not on the same version number movements. Developers and designers must agree on guidelines for how the interface and implementation version numbers move. For example, they might agree that implementations must always have the same major version number as their interface but that the minor versions can be different. Potentially nine instances of the interface and nine instances of the implementation are deployed if three versions per version level are deployed. It is more difficult to track because of the two distinct numbers. It is difficult to quickly determine which implementation that a particular interface is using.

Summary of strategies.

The following table compares the four strategies to help you make the best choice for your services and APIs.

Strategy comparison.

Each level has three instances. Changes that are compatible with an earlier version are not automatically migrated.

Each level has three instances. All changes that are compatible with an earlier version are automatically migrated.

استنتاج.

In this article, you learned about the importance of versioning and four strategies to help you manage it. Many more strategies are possible that were not addressed in this article. Keep in mind that no strategy is a single perfect fit.

Downloadable resources.

مواضيع ذات صلة.

Sign in or register to add and subscribe to comments.