في المقالة الأخيرة في هذه السلسلة ، ستتعرف على توصيات REST API وأمثلة التطوير من Java و Spring Web Services.
عند تطوير واجهة برمجة تطبيقات REST جيدة ، من المهم أن يكون لديك خدمات ميكروية جيدة.
كيف يمكنك تطوير REST API الخاص بك؟ ما هي أفضل الممارسات؟
سوف تتعلم:
- كيفية تطوير واجهة برمجة تطبيقات REST جيدة؟
- ما الذي يجب علي التفكير فيه عند تطوير واجهة برمجة تطبيقات REST؟
- ما هي أفضل الممارسات لتطوير خدمات RESTful على الويب؟
REST API
هذه هي المقالة الأخيرة في سلسلة من المقالات حول REST API:
استخدام المستهلك أولا النهج
من سيستخدم خدمتك؟ خدمات المستهلك.
هل تنظر إلى الخدمة من منظور المستهلك؟
- إذا كنت تقوم بتطوير API ، فهل يستطيع المستهلك فهم API الخاص بك؟
- إذا نشرت مواردك ، فهل يمكن للمستهلك العثور عليها والوصول إليها؟
- يمكن للمستهلك فهم URIs الخاص بك؟
- ما نوع الخدمة التي تقدمها؟
- هل هذا تطبيق محمول أم تطبيق ويب؟
- ماذا يتوقع المستهلكون ، وهل يمكن أن تتغير هذه الأنواع من المستهلكين في المستقبل؟
- إذا كنت تنفذ شيئًا مثل HATEOAS ، فكر في كيفية استخدام عملائك له قبل تنفيذه.
- الشيء الأكثر أهمية هو أن يكون لديك وثائق ممتازة
- اجعل الأمور أسهل لعملائك لتوفير الوقت.
- كلما زاد عدد المستهلكين الذين يمكنهم القيام به بمفردهم ، كلما قل العمل بالنسبة لك.
كلما قمت بمناقشة أو مراجعة خدمة ، ضع متطلبات العميل في المقام الأول.
استخدام العقد أولا النهج
ما هو العقد؟
يعتبر منشئ خدمة الويب
مقدم خدمة . تطبيق يستخدم خدمة ويب هو
مستهلك للخدمة .
العقد هو اتفاق بين مزود ومستهلك حول الخدمة.
من أجل استخدام الخدمة بشكل صحيح ، يجب على مستهلك الخدمة فهم العقد بالكامل. يتضمن العقد تفاصيل العديد من جوانب الخدمة ، مثل:
- كيف تتصل بخدمة الويب؟
- أي نوع من النقل يستخدم؟
- ما هي هياكل الطلب والاستجابة؟
وهذا ما يسمى أيضا
تعريف الخدمة .
في النهج الأول للعقد ، تقوم أولاً بتحديد عقد الخدمة ، ثم تقوم بتنفيذ الخدمة فقط.
العقد الأول مع WSDL
على سبيل المثال ، عند تعريف خدمات الويب SOAP ، فإنك تستخدم WSDL لتحديد العقد.
تحدد WSDL ماهية نقاط نهاية الخدمة ، والعمليات التي تنشرها ، وهياكل الطلب والاستجابة.
العقد الأول مع Swagger / Open API
عندما تستخدم خدمات RESTful على الويب ، فإن Swagger هو أداة شائعة لتوثيق خدمات الويب الخاصة بك.
يتيح لك Swagger تحديد الموارد التي تقدمها كجزء من واجهة برمجة التطبيقات. يتضمن تفاصيل كل عملية ، على سبيل المثال ، سواء كانت تستخدم XML أو JSON أو كلاهما. الجواب مخطط هو أيضا هناك.
كما يوفر معلومات مفصلة حول رموز الاستجابة التي يدعمها. يمكنك أيضًا رؤية أن هذا المورد المعين ،
/ jpa / المستخدمين :
يدعم عملية الحصول على. في الواقع ، يدعم أيضًا عملية POST:
نظام الاستجابة ، إذا كان هذا المورد متاحًا ، سيكون:
تعريف كائن المستخدم موجود في اتفاقية Swagger كـ:
ويشمل سمات: تاريخ
الميلاد ،
معرف ،
اسم ومجموعة من رسائل الوظائف. تتضمن بعض الحقول أيضًا حقل وصف بداخلها.
في النهج الأول للعقد ، قبل تنفيذ الخدمة ، تقوم أنت يدويًا أو باستخدام التطبيق بإنشاء التعريف الذي أنشأه Swagger.
فوائد العقد النهج الأول
باستخدام النهج الأول للعقد ، تفكر في عملائك وكيف يمكنهم استخدام هذه الخدمة. أنت لست قلقًا في البداية بشأن تفاصيل التنفيذ.
إذا كنت في المرحلة المبكرة تعلق أهمية كبيرة على التنفيذ ، فإن التفاصيل الفنية تخترق تعريف خدمتك.
تحتاج إلى التأكد من أن تعريف الخدمة الخاص بك لا يعتمد على النظام الأساسي الذي تستخدمه ، سواء كان Java أو .NET أو أي نظام آخر.
تحديد معايير المنظمة ل REST API
من المبادئ التوجيهية المهمة لمعاييرك التنظيمية هي YARAS.
YARAS لتقف على
بعد RESTful API قياسي . يوفر YARAS المعايير والإرشادات والاتفاقيات التي يجب اتباعها عند تطوير خدمات RESTful على الويب. يقدم توصيات للأشياء التالية:
- ماذا يجب أن اسم الخدمات الخاصة بك
- كيف يجب أن هيكل طلبك وردك
- كيف يجب عليك تنفيذ التصفية والفرز وترقيم الصفحات والإجراءات الأخرى
- كيف يجب أن تقترب من الإصدار
- كيف تحتاج إلى نهج وثائق API
نهج موحد لتطوير الخدمة
تحتاج إلى حل العديد من المشكلات المعقدة قبل البدء في تصميم خدمات الويب RESTful. كل ما سبق ، تحتاج إلى معرفة ذلك.
لن ترغب قيادة مؤسستك في أن يكون للفرق التي تتعامل مع الموارد المختلفة أساليب مختلفة لهذه الأشياء.
على سبيل المثال ، من غير المرغوب فيه أن ينظم Team-A تعيين الإصدار استنادًا إلى معلمات الاستعلام ، وأن يستخدم Team-B الإصدار باستخدام URI.
لذلك ، من المهم أن تكون قد حددت معايير تنظيمية واضحة لنهجك في خدمات RESTful على الويب.
YARAS التخصيص تحت الاحتياجات التنظيمية
الشيء الجيد في YARAS هو أنه يمكن تخصيصها لتلبية الاحتياجات الخاصة بالمنظمة. على سبيل المثال ، يمكنك:
- قم بتهيئة شكل هيئات الاستجابة والاستجابة.
- اختيار نظام تحكم إصدار محدد
نظرًا لأن YARAS لديها تغطية شاملة إلى حد ما ، يمكنك التأكد من أنك لم تفوت قرارًا مهمًا واحدًا.
اختيار إطار عمل قياسي لمؤسسة REST API
الأطر النموذجية المستخدمة لإنشاء خدمات RESTful على الويب في عالم Java هي Spring MVC و Spring REST و JAX-RS.
إذا قمت بإنشاء تطبيق إطار / نموذج أصلي / مرجعي خاص بالمؤسسة يلتزم بمعايير المؤسسة العامة بالإضافة إلى منصة REST API المفضلة لديك ، فإن هذا سيتيح للفرق الالتزام بسهولة بالمعايير المشتركة.
السمات النموذجية تشمل:
- هياكل الطلب والاستجابة
- خطأ في التعامل
- تصفية
- بحث
- الإصدارات
- دعم الإجابة الخاطئة
- HATEOAS
يوفر الإطار القياسي نهجًا موحدًا لتصميم وتنفيذ الخدمات في جميع أنحاء المؤسسة.
إدارة API REST اللامركزية
قم بإنشاء مجموعة من الخبراء من الفرق التي تنشئ واجهة برمجة تطبيقات REST وتشكل فريق إدارة. الفريق مسؤول عن
- تحسين معايير API REST
- بناء / تصميم REST API Framework الخاص بك
استخدام واسع النطاق ل HTTP
عندما تفكر في خدمات RESTful على الويب ، فكر في HTTP.
يحتوي HTTP على جميع الميزات التي تساعدك في إنشاء خدمات ويب رائعة.
استخدم طرق طلب HTTP الصحيحة
فكر في طرق طلب HTTP التي تحتاج إلى استخدامها. عندما تفكر في تنفيذ عملية ما ، حدد المورد الذي يجب إجراؤه عليها ، ثم ابحث عن طريقة طلب HTTP المناسبة. هل تسترجع التفاصيل أو تنشئ شيئًا ما أو تقوم بتحديث شيء موجود أو تحذف شيئًا موجودًا؟
باستخدام طرق HTTP:
- الحصول على الحصول عليها
- وظيفة لخلق
- وضع للتحديث
- حذف لحذف
- التصحيح للحصول على التحديثات الجزئية
استخدم حالة استجابة HTTP المناسبة
عند إجراء العملية ، تأكد من إرجاع حالة الاستجابة الصحيحة.
على سبيل المثال ، عند عدم العثور على مورد معين ، لا تقم باستثناء استثناء خادم. بدلاً من ذلك ، أرسل رمز الاستجابة المناسب في رسالة استجابة ، مثل
404 .
إذا كان هناك بالفعل استثناء خادم ، فأرسل الكود
500 مرة أخرى.
في حالة فشل التحقق من الصحة ، أرسل رمز الطلب غير الصحيح.
التركيز على الأداء
يمكن أن يحتوي كل مورد على عدة تمثيلات - بتنسيق XML أو JSON. يمكن لمستهلك الخدمة اختيار العرض التقديمي الذي يختاره.
تقوم الخدمة بإرجاع 3 مستخدمين عند إرسال طلب GET. في هذه الحالة ، نحصل على تمثيل JSON لمورد
/ المستخدمين .
عندما لا يشير المستهلك إلى طريقة عرض مفضلة ، فإننا نستخدم JSON.
يمكن للمستهلك إرسال رأس قبول للإشارة إلى العرض.
يحتوي نص الاستجابة الآن على محتوى XML:
استخدم الجمع
دائما استخدام الجمع عند تسمية الموارد.
دعنا ننظر إلى مثال بسيط. افترض أن لدينا خدمة تستضيف مورد مستخدم. فيما يلي وصف كيفية الوصول إليهم:
- إنشاء مستخدم: POST / المستخدمين
- حذف المستخدم: DELETE / users / 1
- الحصول على جميع المستخدمين: الحصول على / المستخدمين
- الحصول على مستخدم واحد: GET / users / 1
تفضيل عدة مستخدمين على مستخدم المستخدم يجعل URI أكثر قابلية للقراءة.
- على سبيل المثال ، إذا استخدمنا / user بدلاً من / users للحصول عليه ، فلن يمرر GET / user الرسالة الصحيحة إلى القارئ.
إنشاء وثائق جيدة
يحتاج المستهلكون إلى فهم كيفية الاستفادة المثلى من الخدمة ، وأفضل طريقة لمساعدتهم هي إنشاء وثائق جيدة.
يمكن لخدمات ويب SOAP استخدام وظيفة WSDL ، في حين أن خدمات RESTful على الويب تحتوي على خيارات Swagger (الآن معيار وثائق Open API).
اختيار التنسيق هو جزء واحد فقط من إنشاء وثائق جيدة. ما هو مهم أيضًا هو توفير الكمية المناسبة من المعلومات لمساعدة المستهلك.
يجب أن تكون الوثائق كاملة وتتضمن النقاط التالية:
- ما هو هيكل الطلب والاستجابة؟
- كيف ينبغي للمستهلك المصادقة على نفسه؟
- ما هي حدود الاستخدام؟
- حدد جميع أنواع رسائل الاستجابة ورموز الحالة المقابلة التي يمكن توقعها من الخدمة.
قم بإنشاء مدخل وثائق REST API شائع
سيكون من المفيد أن يكون لديك بوابة وثائق REST API مشتركة للمؤسسة بأكملها. ألق نظرة على أحد هذه البوابة:
تجمع هذه البوابة جميع الموارد المتاحة في المؤسسة. سيكون لديك واجهة مستخدم مثل Swagger UI فوائدها المضافة. باستخدام Swagger UI ، يمكنك الاطلاع على الوثائق بمزيد من التفاصيل:
يمكن استخدام هذا حتى من قبل المستخدمين غير التقنيين. المعلومات المقدمة هنا تشمل:
- تنسيق الاستجابة المتوقعة
- نوع المحتوى
- رموز الإجابة المدعومة
قد يكون تنسيق الوثائق في نمط الطلب / الاستجابة المباشرة ذا أهمية أيضًا.
دعم الإصدار
يتطلب التحكم في الإصدار تعقيدًا كبيرًا لخدمة ويب. من الصعب للغاية الحفاظ على العديد من الإصدارات المختلفة من نفس خدمة الويب. حاول تجنب ذلك كلما كان ذلك ممكنًا.
ومع ذلك ، في بعض السيناريوهات ، يكون التحكم في الإصدار أمرًا لا مفر منه.
لنبدأ من خلال النظر في خدمة مثال. لنفترض أننا حددنا في البداية خدمة بها فئة
PersonV1 على النحو التالي:
لا يأخذ هذا الإصدار من الفصل في الاعتبار أنه يمكن أن يحتوي الاسم على العديد من الأقسام الفرعية ، مثل الاسم الأول والأخير. تحقق من ذلك:
تم تحديث الإصدار الثاني من الفئة المصدر لإصلاح هذه الحالة الشاذة:
لا يمكننا نقل الخدمة بأكملها على
الفور لاستخدام
PersonV2 ! قد يكون هناك مستهلكون آخرون ينتظرون الردود بتنسيق
PersonV1 .
هذا هو المكان المطلوب التحكم في الإصدار.
دعونا الآن نلقي نظرة على الخيارات المتاحة لدينا للتحكم في إصدار هذين المصدرين.
باستخدام URIs مختلفة
لدينا خيار واحد - لاستخدام URIs مختلفة لهذه الموارد المختلفة. في رمز الامتحان أدناه ، نستخدم URIs
v1 / person و
v2 / person لتمييزها:
إذا قمت بتنفيذ طلب GET
للمصدر v1 / person :
سوف تتلقى معلومات تتوافق مع
v1 . لمورد آخر:
باستخدام المعلمة الاستعلام
يستخدم أسلوب التحكم الإصدار الثاني المعلمة الاستعلام:
في URI
/ person / param ، إذا أرسلنا المعلمة
بالإصدار = 1 ،
فسنعيد موردًا من النوع
PersonV1 :
لنفس URI ، تقوم المعلمة ذات
الإصدار = 2 بإرجاع مورد من النوع
PersonV2 :
تسمى هذه الطريقة تعيين الإصدار باستخدام معلمات الاستعلام.
باستخدام رأس (رأس)
هناك طريقة أخرى يمكنك القيام بها وهي التحكم في الإصدار عن طريق تحديد العنوان. هنا نستخدم رأسًا يسمى
X-API-VERSION ونضع علامة على URI كـ
/ person / header . عندما تكون قيمة الرأس
1 ،
يتم إرجاع مورد من النوع
PersonV1 :
عندما تكون قيمتها
2 ، يتم استرداد مورد من النوع
PersonV2 :
نحن نستخدم السمة الموجودة في رأس الطلب لإجراء التحكم في الإصدار بالنسبة لنا.
باستخدام قبول الرأس
تستخدم الطريقة النهائية لإنشاء إصدارات "قبول الرأس". إذا تضمن المستهلك معلومات الإصدار الأول في "قبول رأس" طلب GET ، يتم إرجاع المورد التالي:
خلاف ذلك ،
يتم إرجاع مورد من النوع
PersonV2 :
تسمى طريقة التحكم في الإصدار "
قبول إصدار الرأس" أو
"تعيين نوع الوسائط" ، لأن أنواع MIME عادة ما تكون محتويات "رأس القبول".
مقارنة بين أساليب التحكم في الإصدار
لقد شاهدنا حتى الآن أربعة أنواع من الطرق في الإصدارات:
- باستخدام URIs مختلفة
- باستخدام المعلمة الاستعلام
- استخدام الرأس
- باستخدام قبول رأس / نوع الوسائط
أيهم الأفضل؟ الحقيقة هي أنه لا توجد إجابة واحدة على هذا السؤال. حقيقة الأمر هي أن عمالقة الإنترنت المختلفة يرعون أنواعًا مختلفة من الإصدارات.
- باستخدام URIs مختلفة - تويتر
- باستخدام معلمة الاستعلام - Amazon
- باستخدام رأس - مايكروسوفت
- استخدام قبول رأس / نوع الوسائط - جيثب
تحتاج إلى تقييم هذه الخيارات الأربعة وفقًا لاحتياجاتك المحددة. هناك عدد من العوامل المهمة التي يجب مراعاتها:
- تلوث URI : من خلال التحكم في الإصدارات باستخدام URIs ومعلمات الاستعلام ، ينتهي بنا الأمر إلى تلويث مساحة URI. هذا لأننا نضيف البادئات واللواحق إلى السلاسل الرئيسية لمعرف URI. التحكم في الإصدار باستخدام رأس يتجنب هذا.
- إساءة استخدام رؤوس HTTP . في حالة التحكم في الإصدار باستخدام الرؤوس ونوع الوسائط ، يتم إساءة استخدام رؤوس HTTP لأنها لم تكن في الأصل مخصصة للتحكم في الإصدار.
- التخزين المؤقت : يتم تعريف المورد من خلال URI الخاص به. ومع ذلك ، إذا كنت لا تستخدم URI لتحديد نسخته ، ولكنك تستخدم آلية قائمة على الرأس ، فلن يمكن تخزين معلومات الإصدار في ذاكرة التخزين المؤقت. إذا كان التخزين المؤقت لـ HTTP مهمًا لك ، فاستخدم التحكم في الإصدار بناءً على URI أو معلمة الطلب.
- إمكانية تنفيذ طلب المستعرض : تتطلب الإصدارات على أساس العنوان ونوع الوسائط أدوات مثل ساعي البريد. ومع ذلك ، إذا لم يكن مستهلكو الخدمة أذكياء من الناحية الفنية ، فمن الأفضل استخدام التحكم في الإصدار استنادًا إلى معلمة URI أو استعلام.
- وثائق واجهة برمجة التطبيقات : تحتاج أيضًا إلى التفكير في الطريقة التي تريد بها توثيق واجهات برمجة التطبيقات. إصدار المستند إلى URI ومعلمة الاستعلام أسهل في توثيق من النوعين الآخرين من التحكم في الإصدار.
نفهم أنه لا يوجد حل مثالي واحد!
فكر في معالجة الأخطاء
عندما يرسل المستهلك طلبًا إلى خدمة ما ، من المهم أن يتلقوا الإجابة الصحيحة. كلما حدث خطأ ما ، من المهم إرسال استجابة مناسبة.
عندما يطلب المستهلك مورد غير موجود
إذا أرسلنا طلب GET للبحث عن مستخدم حالي ، فسوف نحصل على الاستجابة التالية:
إذا كنت تبحث عن مستخدم غير موجود:
ما تحصل عليه هو
404 حالة
غير موجود . هذا خطأ في معالجة جيدة لأنه يحدد بشكل صحيح أنه لم يتم العثور على المورد ولا يُرجع خطأ في الخادم.
دعنا الآن نرسل طلب GET إلى URI غير موجود:
كما ترى ، تحصل على
404 حالة استجابة
لم يتم العثور عليها . يشير عنوان URL غير صالح إلى مورد غير موجود.
حالات استجابة مهمة
- 200 - النجاح
- 404 - مورد غير موجود
- 400 - طلب غير صالح (على سبيل المثال ، خطأ في التحقق من الصحة)
- 201 - خلقت
- 401 - غير مصرح به (في حالة فشل المصادقة)
- 500 - خطأ في الخادم
تفاصيل الخطأ في نص الاستجابة
يساعد هذا إذا كان لديك بنية استثناء قياسية عند تطوير الخدمة.
للأخطاء المحددة ، قد يتم إرجاع هياكل استجابة محددة إلى المستهلك ، وقد يكون هذا هو المعيار في جميع أنحاء المنظمة. تأكد من أن استجابة الخطأ قابلة للقراءة أيضًا للمستهلكين ، دون أي تشويش.
باستخدام Swagger أو فتح وثائق API
يوفر Swagger أحد أكثر تنسيقات المستندات شيوعًا لخدمات RESTful على الويب. اليوم يتم دعمه من قبل مختلف المنظمات ويستخدم في عدد كبير من الخدمات. هنا ننظر إلى جانبين رئيسيين من Swagger:
- تنسيق وثائق اختيال
- Swagger UI ، والذي يسمح لك بالاطلاع على وثائق Swagger بطريقة مريحة بصريًا
وثائق اختيال
ألقِ نظرة على Swagger JSON التالية:
في المستوى الأعلى ، يبدو هذا مشابهًا جدًا لتعريف WSDL. لديها العديد من السمات المهمة:
- المضيف : حيث تقع الخدمة
- basePath : المسار حيث توجد الخدمة
- يستهلك : ما يتم قبول الطلبات
- ينتج : ما أنواع الاستجابات التي يتم إنشاؤها
- مسارات : موارد متنوعة متوفرة في هذه الحالة ، لديك عدة أنواع من الموارد في القائمة:
Swagger, , , :
/users GET POST .
GET . :
,
200 User .
User definitions () :
Swagger , RESTful -. JSON.
Swagger UI
Swagger UI — , Swagger - RESTful. :
, - . :
, :
, URL :
GET , :
, .
birthDate ,
id ,
links ,
name postsعرض أيضا. يمكنك أيضًا تشغيل استعلام مثال وعرض الاستجابة:
باستخدام Swagger Tools (Open API Standard)
إن الشيء العظيم في Swagger هو الأدوات العديدة المتوفرة حوله. ألق نظرة على الخدمة التالية التي استخدمناها سابقًا لشرح التحكم في الإصدار: فيما يلي نظرة على الوثائق التي تم إنشاؤها تلقائيًا لهذه الخدمة:
يحتوي Swagger على دعم لكل من نهج العقد الأول ونهج الشفرة الأولى.في هذه المشكلة ، يوجد فيديو للمؤلف .ملخص
في هذه المقالة ، بحثنا في أفضل الممارسات لإنشاء وتصميم خدمات الويب RESTful.قراءة إضافية
كن الأفضل في واجهة REST API الخاصة بك!تطوير REST APIs