ما هي أساليب إصدار إيجابيات وسلبيات API

Question

لقد لاحظت في بعض الأمثلة طريقتين لإصدار API.

واحد منهم يستخدم نسخة في عنوان URL

/api/v1/products

والآخر يستخدم رأس نوع المحتوى ورأس قبول للاحتفال بإصدار API للبيانات التي يتم إرسالها إلى الخادم

Content-Type=application/vnd.company.v2+xml

ما هي إيجابيات وسلبيات لهذه الأساليب؟ ما هي بعض حالات الاستخدام حيث ستستخدم كل نهج؟

Answer 1

لقد اعتدت على الحصول على رقم الإصدار في عنوان URL نفسه (/v1/). أنا شخصياً أعتقد أن هذا نهج أكثر نظافة - بهذه الطريقة ، لا يحتاج المستخدم النهائي (أو المطور) إلى التعامل مع رؤوس HTTP ، ويمكنه ببساطة تعديل API/Call للوصول إلى إصدارات مختلفة من واجهة برمجة التطبيقات حسب الحاجة.

أعتقد أنه من الممكن أيضًا أن لا يتمتع بعض واجهات برمجة تطبيقات HTTP الموجودة في لغات مختلفة بدعم كامل لرؤوس HTTP ، لذلك يمكنك دائمًا جعل واجهة برمجة التطبيقات متاحة بسهولة للمستخدم النهائي. إعادة كتابة عنوان URL هي أبسط طريقة ، ويجب أن تعمل مع أي شيء يدعم HTTP هناك.

أخيرًا ، السماح بتحديد إصدار API باستخدام عنوان URL يتيح اختبارًا بسيطًا باستخدام متصفح الويب. إذا قمت بدمج الإصدار في رأس HTTP ، فسيُجبر المطور على استخدام لغة برمجة لإجراء الاختبار.

Answer 2

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

فيما يلي إيجابيات وسلبيات يمكن أن أجدها (أنا متأكد من أن هناك المزيد ، وبعض السلبيات لها عمل حولها لم يتم ذكرها هنا)

1. إنه أكثر استكشافًا. بالنسبة لمعظم الطلبات ، يمكنك فقط استخدام متصفح ، في حين أن تطبيق رأس الموارد يتطلب نهجًا أكثر برمجية للاختبار. ومع ذلك ، نظرًا لأن جميع طلبات HTTP لا تُنسى ، على سبيل المثال ، طلبات النشر ، يجب عليك استخدام مكون إضافي عميل REST مثل ساعي البريد أو كف. uri pro/header con

2. مع واجهة برمجة تطبيقات URI-Versioned ، يتم تحديد تحديد الموارد وتمثيل المورد معًا. هذا ينتهك المبادئ الأساسية للراحة ؛ يجب تحديد مورد واحد بواسطة نقطة نهاية واحدة فقط. في هذا الصدد ، يعد اختيار إصدار رأس الموارد أكثر مثالية أكاديميًا. رأس برو/أوري كون.

3. واجهة برمجة تطبيقات URI-versioned هي أقل عرضة للخطأ وأكثر دراية لمطوري العملاء. يسمح الإصدار بواسطة URL للمطور بمعرفة إصدار الخدمة في لمحة. وينسى مطور العميل تضمين إصدار مورد في الرأس ، عليك أن تقرر ما إذا كان ينبغي توجيهها إلى أحدث إصدار (والذي يمكن أن يسبب أخطاء عند زيادة الإصدار) أو خطأ 301 (تم نقله دائمًا). في كلتا الحالتين ، هناك المزيد من الالتباس لمطوري العملاء المبتدئين. uri pro/header con
4. يفسر إصدار URI نفسه لخلط إصدارات متعددة في نفس التطبيق. في هذه الحالة ، لا يتعين عليك زيادة تطوير إطارك. ملاحظة: إذا قمت بذلك ، فمن المرجح أن تحتوي بنية الدليل على كمية كبيرة من التعليمات البرمجية المكررة في دليل V2. أيضًا ، يتطلب نشر التحديثات إعادة تشغيل النظام - وبالتالي يجب تجنب هذه التقنية إن أمكن. uri pro/header con.
5. من الأسهل إضافة الإصدار إلى رؤوس HTTP لمشروع موجود لم يكن لديه بالفعل إصدار في الاعتبار من بدايته. رأس برو/أوري كون.
6. بحسب ال RMM المستوى 3 مبدأ الراحة: ضوابط Hyper Mediledia, ، يجب عليك استخدام رؤوس قبول HTTP ورؤوس المحتوى للتعامل مع إصدار البيانات وكذلك وصف البيانات. رأس برو/أوري كون.
7. عندما تضع الإصدار في عنوان URL ، يحتاج عملاؤك إلى تنسيق تغيير التعليمات البرمجية الخاصة بهم (أو إذا كانت ذكية ، تكوينها) ، إلى واجهة برمجة التطبيقات الجديدة. رأس برو/أوري كون.

فيما يلي بعض الروابط المفيدة إذا كنت ترغب في القيام ببعض القراءة الإضافية:

• وصف مارتن فاولر لنموذج نضج ريتشاردسون
• إصدار API - مختبرات محورية
• هاتوس
• مقالة Informit.com حول خدمات REST للإصدار

Answer 3

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

1. أفضل الممارسات لتصميم واجهة برمجة التطبيقات البراغماتية - الإصدار عبر عنوان URL ، وليس عبر الرؤوس.
2. المبرمجين : ما هو النمط الموصى به لتخطيط نقاط نهاية الراحة للتغييرات التي تم النظر فيها؟

TL ؛ DR الجواب: استخدام الإصدار # في عنوان URL هو النهج الموصى به.

بعض من أكثر البئرات التي صادفتها- Instagram API و Stackoverflow.com API - كلاهما يستخدم هذا النهج لإصدار API.