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

طرق إصدار أبي، الجزء 2.

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

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

المهندس المعماري واجهة الإصدار:

استخدام مخططات أوري العينية: / أبي / collection_name / resource_id اتبع تعريفات أساليب هتب يجب أن تكون الموارد دائما متوافقة مع الإصدارات السابقة يجب إزالة الموارد عبر الإصدارات على أي حال يمكن معالجة الموارد المنقولة عن طريق إعادة توجيه رموز هتب.

تمثيل موارد الإصدار:

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

تصميم أبي نسخة أقل.

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

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

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

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

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

جيت / أبي / فو / أو جيت / أبي / فو / 1 استرداد الموارد أو مجموعات الموارد و إديمبوتنت (تكرار مع نفس النتائج) بوست / أبي / فو / يخلق موارد جديدة وليس إديمبوتنت (تكرار يخلق المزيد من الموارد) بوت / أبي / فو / 1 تحديثات أو إنشاء مورد محدد كامل و إدمبوتنت باتش / أبي / فو / 1 (معيار مقترح) بتحديث حقول مورد معين و إديمبوتنت ديليت / أبي / فو / 1 حذف مورد (أحيانا مجموعات الموارد) و إديمبوتنت.

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

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

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

جار تمثيل تمثيل الموارد.

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

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

I & # 8217؛ ليرة لبنانية القفز في وكنت قد تنظر في ما يلي:

حتى من دون فهم كامل لرأس قبول، يمكنك ربما تخمين هذه السلسلة يعني أنه يتوقع نوع التطبيق / vnd. example. foo في تنسيق جسون، الإصدار 2 إن وجدت، وأي إصدار خلاف ذلك. تحليل رأس قبول بطريقة تتفق مع المواصفات يمكن أن يكون صعبا فقط لأن العديد من المكتبات لا تحليله من خارج منطقة الجزاء.

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

الآن، كيف أفعل هذا؟

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2) رأس قبول.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مرة أخرى في اليوم كانت خدمات الويب المعيار الفعلي للوصول إلى "أنظمة التسجيل". خدمات ويب سواب & هيليب؛

إصدار أبي الخاص بك هو الخطأ، وهذا هو السبب قررت أن تفعل ذلك 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؛ ولكن الأهم من ذلك، إذا بوكر هو بوند مرة أخرى أستطيع أن أذكر خرق شيء مثل Gawker2017 وعنوان يمكن أن يكون شيئا ودية على غرار & # x201C؛ قاذف (الجيش السوري هجوم الكتروني) & # x201D؛. وهو يقسم ما هو مستقر ويمكن التنبؤ به من ذلك الذي لا يعني أنه يمكن للأشخاص إنشاء تبعيات مثل الصور أو الأصول الأخرى على السمة نيم.

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

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

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

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

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

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

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

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

ورل: يمكنك ببساطة إختراق إصدار واجهة برمجة التطبيقات في عنوان ورل، على سبيل المثال: هاريبينبوند / أبي / v2 / برياكثداكونت / فو رأس طلب مخصص: يمكنك استخدام عنوان ورل نفسه كما كان من قبل ولكن أضف رأسا مثل & # x201C؛ أبي-فيرسيون: 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 مثل البيانات: هذا هو دلالة من المواصفات هتب وكما أن الدلالات الدلالية لأفعال الطلب تجعل الكثير من المعنى (أي أننا نحصل على أو نضع أو حذف أو نشر) وكذلك الطريقة التي يرغب العميل في تمثيل المحتوى.

By no means does this mean that I think the other two are wrong and frankly, there’s no better way to share the API with someone than to say “Here, click this”, but when I can easily construct the request and manage the headers, I’ve gone with this route.

Actually, come to think of it, I also use the version in the domain route. لماذا ا؟ Just through the process of writing this API I was constantly communicating with people about the ways of querying it (more on that later) and the attributes it returns. Being able to go flick an email and say “Hey, here’s what I’m thinking” and they simply click it and get results is invaluable. This is the point that proponents of the URL versioning approach quite rightly make: you simply cannot do this when you’re dependent on headers.

Oh, and in case you’re checking up on me, at the time of writing I haven’t yet rolled the site over to v2 of the API. Now that the breach data is pulled back in the API when a search occurs it means I have the luxury of not loading all breaches into the source on initial load (that was never going to be sustainable as the data set expands). This’ll save a bunch of outbound traffic and speed things up for people in terms of getting the site loaded, but it also means just a little more work on my end. ترّقب.

في الختام.

Clearly I’ve been a little tongue-in-cheek here with regards to everything being wrong but honestly, the more you read on this and the more questions you ask, the more wrong every route seems in one way or another. In fact I know damn well that there are aspects of my implementation that will be referred to as “wrong” (I can think of at least a couple) and naturally I’m bracing for the potential onslaught of feedback to that effect. The thing is though, each of these options works and frankly, for all practical purposes, they work just as well as each other.

If I may leave others considering how to version their APIs with a final thought: Nobody will use your API until you’ve built it. Stop procrastinating. None of these are “bad” in any tangible sense, they’re just different. They are all easily consumable, they all return the same result and none of them are likely to have any real impact on the success of your project.

المراجع.

Stack Overflow: Best practices for API versioning? (great question, great answers, closed as “not constructive”, I assume because “Bill the Lizard” got out on the wrong side of bed that morning) Lexical Scope blog: How are REST APIs versioned? (good comparison of versioning practices across services. albeit now a couple of years old) CodePlex: Routing constraint sample (linked in from Microsoft’s Web API page as an example of versioning APIs by adding a custom header) CodeBetter: Versioning RESTful Services (very pragmatic and a good description of the various ways an API might change) Vinay Sahni’s blog: Best Practices for Designing a Pragmatic RESTful API (he’s arguing for URL versioning for the sake of “browser explorability”) Pivotal Lans: API versioning (good view of the conflicting opinions out there) Web Stack of Love: ASP Web API Versioning with Media Types (good end-to-end walkthrough of creating an app to support versioning by content negotiation)

Hi, I'm Troy Hunt, I write this blog, create courses for Pluralsight and am a Microsoft Regional Director and MVP who travels the world speaking at events and training technology professionals.

Hi, I'm Troy Hunt, I write this blog, create courses for Pluralsight and am a Microsoft Regional Director and MVP who travels the world speaking at events and training technology professionals.

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

I usually run private workshops around these, here's the upcoming public events I'll be at:

Don't have Pluralsight already? How about a 10 day free trial? That'll get you access to thousands of courses amongst which are dozens of my own including:

“The Cloud Never Goes Down”, Azure SLAs and other availability trivia.

Here’s how Bell was hacked – SQL injection blow-by-blow.

Subscribe Now!

Copyright 2017, Troy Hunt.

This work is licensed under a Creative Commons Attribution 4.0 International License. In other words, share generously but provide attribution.

تنصل.

Opinions expressed here are my own and may not reflect those of people I work with, my mates, my wife, the kids etc. Unless I'm quoting someone, they're just my own views.

Published with Ghost.

This site runs entirely on Ghost and is made possible thanks to their kind support. Read more about why I chose to use Ghost.

Four REST API Versioning Strategies.

This article describes four common REST API versioning strategies and explains how we version the REST API at xMatters.

At xMatters, we follow the SemVer specification – we update the API major version whenever we introduce breaking changes. Internally, we update minor and patch versions whenever we add functionality and backward-compatible updates. When we release a new major version of the xMatters REST API, clients can choose to either continue using an existing major version or migrate to the new one.

REST is by far the most prominent architectural style used today to expose services to third parties over the internet. It uses the HTTP standard instead of more complex protocols like SOAP or RPC. The reason REST has been so successful is that it mimics how the web works:

Stateless: Doesn’t retain client context between requests Cacheable: Relies on HTTP caching rules Client/Server oriented: Separates concerns between clients and servers Layered: Leverages a layered system and a unified interface.

Four common REST API versioning strategies.

There are four common ways to version a REST API.

1. Versioning through URI Path.

One way to version a REST API is to include the version number in the URL path.

This strategy is used by xMatters as well as other companies such as Facebook, Twitter, Airbnb, and others.

This solution often uses URI routing to point to a specific version of the API. Because cache keys (in this situation URIs) are changed by version, clients can easily cache resources. When a new version of the REST API is released, it is perceived as a new entry in the cache.

The internal version of the API looks as follows:

Major version: The version used in the URI and denotes breaking changes to the API. Internally, a new major version implies creating a new API and the version number is used to route to the correct host.

Minor and Patch versions: These are transparent to the client and used internally for backward-compatible updates. They are usually communicated in change logs to inform clients about a new functionality or a bug fix.

This solution has a pretty big footprint in the code base as introducing breaking changes implies branching the entire API.

2. Versioning through query parameters.

Another option for versioning a REST API is to include the version number as a query parameter.

This is a straightforward way of versioning an API from an implementation point of view. It is also easy to default to the latest version if a query parameter is not specified.

The main drawback comparing to the URI versioning is the difficulty of routing. Query parameters are in fact more difficult to use for routing requests to the proper API version.

3. Versioning through custom headers.

REST APIs can also be versioned by providing custom headers with the version number included as an attribute.

The main difference between this approach and the two previous ones is that it doesn’t clutter the URI with versioning information.

4. Versioning through content negotiation.

curl - H “Accept: application/vnd. xm. device+json; version=1 ” example/api/products.

The last strategy we are addressing is versioning through content negotiation.

This approach allows us to version a single resource representation instead of versioning the entire API which gives us a more granular control over versioning. It also creates a smaller footprint in the code base as we don’t have to fork the entire application when creating a new version. Another advantage of this approach is that it doesn’t require implementing URI routing rules introduced by versioning through the URI path.

One of the drawbacks of this approach is that it is less accessible than URI-versioned APIs: Requiring HTTP headers with media types makes it more difficult to test and explore the API using a browser.

Content negotiation is a more granular approach because it versions resource representations instead of versioning the entire API, but it also comes with a high implementation cost for both clients and developers. More often than not, content negotiation needs to be implemented from scratch as there are few libraries that offer that out of the box. The other approaches are easier to implement and use but limit the developer’s ability to refactor due to the high cost of introducing breaking changes to the API contract.

Any thoughts or recommendations? ترك تعليق أدناه!

Free White Paper: Learn About Standard+Case.

Learn more about taking a holistic approach to IT from Rob England at his blog, The IT Skeptic, and from his books, including Plus! The Standard+Case Approach. For more information, read Rob’s new white paper on turning undefined Case Management situations into new Standard Response Models, written for xMatters: Standard+Case: How IT Response Models Drive Modern Operations.

Do we need to make packging (folder) as per the major version ?

Another question is, How the version the schema if Api change require change in database tables. any link ?

One thing that is not very often documented is how to manage the code and all the versions that are supported by the API.

I’m interested to find a good pattern to manage our code and avoid version nightmare.

My implementation of 3rd approach for spring-webmvc:

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

How We Hacked the Airbnb experience with AT&T, HP, and Intel.

New ServiceNow Integration Reduces Time to Resolve.

Moogsoft and xMatters Integration Takes Incident Management to a New Level.

Zombie Jobs Can’t Be Stopped By Email Broadcasts.

Need support?

Our dedicated community site is the best place to get help on all xMatters products. Our team of expert support staff and users inside our community can help you get the right answer.

REST APIs don’t need a versioning strategy – they need a change strategy.

Change in an API is inevitable as your knowledge and experience of a system improves. Managing the impact of this change can be quite a challenge when it threatens to break existing client integrations.

Developers often try to decide on a versioning strategy as soon as they start work on an API. This is understandable but it’s not always the smartest way of looking at the problem of managing change. Brandon Byers summed this up by borrowing Jamie Zawinski’s dig at regular expressions:

Some people, when confronted with a problem, think “I know, I’ll use versioning.” Now they have 2.1.0 problems.

How can you version resources in REST?

REST doesn’t provide for any specific versioning but the more commonly used approaches fall into three camps: putting it on the URI, using a custom request header or a adding it to the HTTP Accept header.

Using the URI is the most straightforward approach though it does upset REST advocates who insist that a URI should refer to a unique resource. You are also guaranteed to break client integrations when a version is updated no matter how heavily you invest in creative routing and client communication.

A custom header allows you to preserve your URIs between versions though it is effectively a duplicate of the content negotiation behaviour implemented by the existing Accept header. A client can use this header to send a list of supported versions while the server responds with the version used in the Content-Type header.

Content negotiation may let you to preserve a clean set of URLs but you still have to deal with the complexity of serving different versions of content somewhere . This burden tends to be moved up the stack to your API controllers which become responsible for figuring out which version of a resource to send. The end result tends to be a more complex API as clients have to know which headers to specify before requesting a resource.

The version number isn’t the problem.

Given the contentious nature of REST, you’ll always be wrong in somebody’s eyes no matter what approach you take. The point is that version numbering itself is a red herring.

The real challenge here is in managing a code base that can serve up multiple versions of resources. If you keep all versions in the same code base then older versions become vulnerable to unexpected changes. If you separate the code bases then the operational and support overhead escalates. In both cases, code bloat and increased complexity are an inevitable consequence.

A strict approach to versioning does give you much-needed certainty over the contract but it does tend to undermine a system’s capacity to change . Versioning can become a barrier to improvement as any requirements that lead to version changes are resisted. I have seen APIs with strict versioning policies stuck on the same version for years due to legitimate concerns over the amount of work and risk involved in change.

What’s the alternative to versioning?

A coherent version strategy should address how you will manage change in your API whilst providing a stable contract to clients. This doesn’t have to include issuing new versions in response to changes.

One approach is to build in the possibility of change by making provision for backwards compatibility in API changes. This approach does carry significant risk as you cannot be sure that a change will not break existing clients even with exhaustive regression testing.

You can even take backwards compatibility a step further by adding features such as optional parameters and wildcard properties that anticipate future changes. This kind of “ forwards compatibility ” tends to produce a coarse contract that places a considerable burden of validation onto the client. The end result is often a messy set of switches and codes required for each call.

Bertrand Meyer’s Open\Closed principle suggests that software entities should be “open for extension, but closed for modification”. When applied to APIs the implication is that you can augment your resources but not change them.

This approach could offer the certainty of stricter versioning without the regression risks involved in backwards compatibility. Augmentation is not without its problems though as it can give rise to bloated contracts. Without careful discipline an API can become littered with duplicate methods or resources that provide several slightly different ways of achieving the same thing.

Can you share the responsibility?

You could do more to share the burden of change between API and client. Postel’s law, often referred to as the Robustness principle, states that you should be “liberal in what you accept and conservative in what you send”. In terms of APIs this implies a certain tolerance in consuming services.

For example, strict serialization techniques can be unnecessarily intolerant of change. A more tolerant reader should only be concerned with data that it needs and ignore every other part of the response. This means that the majority of changes are unlikely to break the integration.

Another approach could be for the consumer to declare the data they are interested in as part of a request. This consumer-driven contract pattern does not specify the form that these consumer assertions should take, but an implementation could allow an API to detect when a request is out of date.

Unfortunately, these approaches can only be applied to relatively closed communities of services. Public-facing APIs rarely have the luxury of being able to dictate the style of client integration. The only enforceable contract you have between service and client is made up of the data and protocol.

This is why careful discipline is at the heart of any sensible change strategy. A good API doesn’t come into being by accident. It has to be curated . Whatever approach you take to managing change you will need consistent and active governance over the evolving contract.

I am a London-based technical architect who has spent more than twenty years leading development across start-ups, digital agencies, software houses and corporates. Over the years I have built a lot of stuff including web sites and services, multi-screen applications, systems integrations and middleware.

My current focus is on enabling scalable SaaS delivery and providing architectural leadership in agile environments. I currently work for SaaS provider Fourth leading them to enterprise heaven, one service at a time.

You can follow me on Twitter or check me out on LinkedIn.

Entity services: when microservices are worse than monoliths.

Finely-grained, entity-based services seem to be advocated by some pretty authoritative sources. This is unfortunate as they are something of an anti-pattern that can undermine many of the benefits of decomposing an monolith into micoservices.

Forget code coverage – test design should be driven by behaviours.

Test coverage statistics are much loved by management teams and code quality tools. They tend to associate a high level of coverage with robust, well-managed code bases. Wrongly, as it turns out.

Events, sagas and workflows: managing long-running processes between services.

An event-driven architecture can give rise to complex chains of events that are difficult to manage. These problems can be mitigated through careful design rather than resorting to shared state databases or workflow engines.

Technical debt is an overused and lazy metaphor.

Technical debt may be a useful metaphor for describing how bad code design undermines productivity to non-technical audiences, but it does not help in understanding the longer term problems that affect code bases.

How can Domain Driven Design help with large scale agile development?

Agile teams spend time modelling software whether they are prepared to admit it or not. Adopting a technique like Domain Driven Design can help to make this more efficient, particularly at scale.

Running a Core console application as a Windows Service.

Although Core does not directly support creating Windows Services there are several different ways of creating applications that can be registered and run as services.

When does refactoring become rewriting?

Refactoring describes a very specific and controlled technique for improving code. The problem is that it is often used to describe wholesale changes to code bases that should be treated as a rewrite.

Writing unit tests for Azure Functions using C#

You can now write compiled Azure functions in C# with full unit test coverage, though there are a few obstacles along the way.