شلل واجهة برمجة التطبيقات (REST API) - أفضل الممارسات والأمثلة

عناوين REST API (لا تخلط بينها وبين RESTful APIs) تلعب دورًا كبيرًا في اتصال خدمات الويب. دون إبطاء، دعونا نلقي نظرة فاحصة على ما هي، ولنتعرف على أفضل الممارسات والأمثلة التي يمكن التعلم منها.

💡

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

إذا كنت تجد Apidog مثيرًا للاهتمام، فلا تنتظر أكثر! انقر على الرابط أدناه لبدء استخدام Apidog! 👇 👇 👇

button

ما هي عناوين REST API؟

عناوين REST (نقل حالة التمثيل) API (محددات الموارد الموحدة) هي عناوين محددة تستخدم للوصول إلى التفاعل مع الموارد ضمن RESTful API محددة. هذه العناوين فريدة، وكل واحدة تقود إلى بيانات أو وظائف محددة ضمن REST API.

هيكل عناوين REST API

لكي نتمكن من إعادة إنتاج عناوين REST API بطريقة موحدة، تحتوي عناوين REST API على هيكل مشترك يتكون من:

البروتوكول: البروتوكولات تكون عادةً في شكل HTTP أو HTTPS، والتي تحدد كيفية الاتصال بالـ API.
المضيف: المضيف يحدد عنوان الخادم الذي توجد فيه API (على سبيل المثال، api.example.com).
المسار: المسار يحدد المورد المحدد داخل API، بدءًا بشرطة مائلة للأمام (على سبيل المثال، /users).
سلسلة الاستعلام (اختياري): سلاسل الاستعلام، التي هي اختيارية، تسمح للمطورين بإضافة معلمات إضافية يمكن أن تقوم بتصفية أو تحسين المورد، باستخدام أزواج المفتاح والقيمة بعد علامة استفهام (على سبيل المثال، /users?name=John).

لماذا نحتاج إلى فهم عناوين REST API؟

هناك مجموعة متنوعة من الأسباب التي تجعل من الضروري أن يفهم مطورو الويب المفهوم الأساسي لعناوين REST API. هذه بعض من الأسباب الرئيسية:

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

أمثلة على عناوين REST API

إذا كنت تتساءل كيف تبدو عناوين REST API، فإليك بعض العينات من العالم الحقيقي لعناوين REST API التي قد تكون قد صادفتها قبل قراءة هذه المقالة!

GitHub: https://api.github.com/users/Bard يسترجع معلومات عن المستخدم "Bard".
OpenWeatherMap: https://api.openweathermap.org/data/2.5/weather?q=London يحصل على بيانات الطقس في لندن.
Unsplash: https://api.unsplash.com/photos/random?count=1 يسترجع صورة عشوائية واحدة.

تظهر هذه عناوين REST API بشكل شائع كعنوان الموقع، الذي يتغير كلما كان هناك حاجة لتبادل البيانات، أو عندما تغير صفحات الويب.

أساسيات عناوين REST API

عند تحديد عنوان REST API الخاص بك، عليك أن تأخذ في اعتبارك بعض المتغيرات والخصائص، مثل:

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

أفضل الممارسات لصياغة عناوين REST API

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

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

مقارنة بين أمثلة عناوين REST API المثلى والسيئة

مارس ترتيب وتسمية الموارد

جيد: https://api.example.com/orders/456/items/789
سيء: https://api.example.com/order_456_item_789

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

الوضوح والدقة

جيد: https://api.example.com/users/123
سيء: https://api.example.com/get_user?id=123

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

التناسق

جيد: https://api.example.com/products/{product_id}
سيء: https://api.example.com/product_detail/abc و https://api.example.com/get_item/xyz

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

Apidog - منصة تطوير REST API

Apidog هي منصة تطوير API قائمة على التصميم الأول، تساعد في أي مواصفات وتعديلات مطلوبة عبر دورة حياة أي API.

apidog design specification — Apidog - منصة تطوير API شاملة

button

يمكن لـ Apidog أيضًا استيراد REST APIs، وتعديل عناوين REST API، واختبار العناوين. لمعرفة كيفية تشغيل Apidog لتعديل REST API الخاصة بك، تابع قراءة القسم أدناه.

تهيئة أساليب وواجهات API

designing api parameters endpoint apidog — تصميم API باستخدام Apidog

السهم 1 - ابتكر عنوان REST API الأمثل لطلبك. تأكد من عدم وجود أخطاء إملائية حتى تحصل على استجابة! تذكر أن تستخدم أفضل الممارسات لعناوين REST API الخاصة بك أيضًا.

السهم 2 - قرر أي أسلوب REST API تريد. الأساليب الأكثر شيوعًا هي GET، POST، PUT، وDELETE. ومع ذلك، يوفر Apidog خيارات لاختيار OPTIONS وHEAD وPATCH.

السهم 3 - اشرح تفاصيل REST API بدقة من خلال تضمين معلمات الطلب، ومعلمات الاستجابة، وأمثلة الاستجابة أدناه. يُوصى بشدة بملء كل شيء حيث سيتم تضمين كل متغير في وثائق API.

تصميم اختبار طلبات API باستخدام Apidog

قبل إطلاق REST API الخاصة بك للجمهور، عليك التأكد من أن API خالية من الأخطاء. من الضروري اختبار كل طلب قمت بتضمينه في خدمات الويب الخاصة بك، لذا اتبع هذه الخطوات للبدء!

select test rest api request apidog — اختيار واختبار طلب REST API واحد

السهم 1 - حدد طلب REST API الذي ترغب في اختباره.

السهم 2- أرسل طلب REST API لتلقي استجابة. قبل الضغط على زر إرسال، تأكد من أن نوع الأسلوب وعنوان URL صحيحان.

السهم 3 - قم بتحليل الاستجابة لمعرفة ما إذا كانت تلبي متطلباتك أو توقعاتك لـ REST API.

إنشاء وثائق REST API

يمكنك تلقائيًا توليد الوثائق المقابلة لـ REST API بحيث يمكن للمطورين المهتمين باستخدام REST API الخاصة بك فهم التفاصيل الدقيقة. قد تشمل هذه التفاصيل هياكل عناوين REST API المثلى.

step by step process sharing api documentation apidog — وثائق REST API قابلة للمشاركة على Apidog

السهم 1 - أولاً، اضغط على زر "مشاركة" على الجانب الأيسر من نافذة تطبيق Apidog. يجب أن تكون قادرًا بعد ذلك على رؤية صفحة "الوثائق المشتركة"، والتي يجب أن تكون فارغة.

السهم 2 - اضغط على زر "+ جديد" تحت "لا توجد بيانات" لبدء إنشاء وثيقة REST API الأولى الخاصة بك باستخدام Apidog.

حدد وضمن خصائص وثائق API المهمة

input api details and select api doc properties apidog — إدخال وتحديد خصائص الوثائق API مع Apidog

يوفر Apidog للمطورين خيار اختيار خصائص وثائق API، مثل من يمكنه رؤية وثائق API الخاصة بك وتعيين كلمة مرور للملف، لذلك يمكن أن يراها فقط الأفراد أو المنظمات المختارة.

عرض أو مشاركة وثائق REST API الخاصة بك

open share edit api documentation apidog — اختر ما يجب القيام به بعد ذلك مع وثائق REST API الخاصة بك!

يمكنك الآن تحديد ما يجب القيام به مع وثائق REST API الخاصة بك. يقوم Apidog بتجميع تفاصيل مشروع API الخاص بك في وثائق API يمكن الاطلاع عليها من خلال عنوان URL لموقع الويب. كل ما عليك فعله هو توزيع عنوان URL حتى يتمكن الآخرون من رؤية وثائق REST API الخاصة بك!

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

الخاتمة

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

تداخل الأسماء موردة بصورة متسقة
استخدام الأسماء الجمع بدلاً من الأفعال

Apidog هي منصة API قوية تتيح للمطورين البناء على أو تعديل واجهات API الجديدة والقديمة.aside from testing and debugging, supports designing new REST APIs, and even importing existing REST APIs!

button