المعلمات هي رؤية شائعة عند التعامل مع واجهات برمجة التطبيقات (APIs) أو خدمات الويب. قد لا تدرك حتى أنك كنت تستخدم المعلمات طوال هذا الوقت! أحد الأماكن الشائعة التي تتفاعل فيها مع المعلمات هي عناوين مواقع الويب. ومع ذلك، هل كنت على علم بأن هناك أنواع مختلفة من المعلمات؟
يمكن أن تكون Apidog خيارًا جيدًا للبدء إذا كنت مهتمًا بالمعلمات. مع واجهة مستخدم بسيطة وبديهية، ابدأ بسرعة من خلال النقر على الزر أدناه! 👇 👇 👇
ستقدم هذه المقالة أساسيات المعلمات، ثم نتناول ما هي المعلمات المسار والاستعلام. سيكون هناك أيضًا قسم يتعلق بنوع السيناريوهات التي تُفضل وجود معلمة مسار بدلاً من معلمة استعلام، والعكس صحيح.
أساسيات أولاً: المعلمات في واجهات برمجة التطبيقات
في واجهات برمجة التطبيقات، المعلمات هي عناصر متغيرة يمكن أن تؤثر مباشرة على وظيفة طلب واجهة برمجة التطبيق. توفر المعلمات واجهات برمجة التطبيقات بتفاصيل أو تعليمات معينة، مما يجعلها مسؤولة عما ستتضمنه واجهة برمجة التطبيقات في ردها.
وظائف المعلمات
لتسهيل الأمور، إليك ثلاث نقاط حول الوظائف التي يمكن أن توفرها المعلمات لمطوري واجهات برمجة التطبيقات:
- تحديد الطلبات: يمكن أن تحدد المعلمات نوع الإجراء الذي ترغب في أن تقوم به واجهة برمجة التطبيقات على مورد معين.
- تخصيص الردود: تؤثر المعلمات على المحتوى أو تنسيق واجهة برمجة التطبيقات التي تم تسليمها ردًا على طلبك.
- تصفية البيانات: تستخدم المعلمات لتصفية النتائج المستلمة من واجهة برمجة التطبيقات.
طرق مختلفة لتنفيذ المعلمات
هناك بعض الطرق لـ تمرير المعلمات في طلبات واجهة برمجة التطبيقات. لاحظ أن هذه هي النقطة التي تتواجد فيها مصطلحات المعلمات المسار والاستعلام.
- مسار URL: هذه هي المتغيرات المدمجة مباشرة في مسار URL، مثل
/users/{id}حيث{id}هو معلمة تمثل معرّف مستخدم معين.
يمكن أن يُشار إلى معلمة{id}هنا على أنها معلمة مسار. - سلسلة الاستعلام: سلسلة الاستعلام هي أزواج مفتاح-قيمة مرفقة بـ URL بعد علامة استفهام (
?)، مثل?limit=10&sort=nameحيثlimitوsortهما معلمتان مع القيم المقابلة.
تسمى أزواج المفتاح-القيمة مثلlimitوsortأيضًا معلمات استعلام. - الرؤوس: هذه هي معلومات إضافية تُرسل مع الطلب، مثل رمز التفويض الخاص بك أو اللغة المفضلة لديك.
- جسم الطلب: يمكن إرسال بيانات معقدة لإنشاء أو تعديل الموارد في جسم الطلب، غالبًا في تنسيقات مثل JSON أو XML.
ما هي معلمات المسار؟
معلمات المسار هي عناصر مدمجة مباشرة داخل مسار URL لطلب واجهة برمجة التطبيقات تعمل كموضع للقيم المحددة. يتم استخدامها لاستهداف وتحديد موارد فريدة داخل واجهة برمجة التطبيقات.
أمثلة على معلمات المسار
/users/{id} هو مثال على معلمة مسار. تمثل معلمة المسار لمستخدم معين (المستخدم هو مورد في هذا المثال).
إذا رأيت هذه الأقواس المعوجة {} في URL، فهي معلمة مسار. ومع ذلك، في الممارسة العملية، لن ترى الأقواس المعوجة على المواقع الإلكترونية حيث يتم استبدالها بالقيم المحددة لعملية واجهة برمجة التطبيقات.
لماذا تستخدم معلمات المسار؟
تُختار معلمات المسار بشكل أساسي من أجل تحديد بيانات أو كيان معين، مثل مستخدم أو منتج، بناءً على معرّف فريد له (ID).
تعتبر معلمات المسار أيضًا وسيلة ممتازة لزيادة قابلية قراءة URL. إنها تجعل عناوين URL أكثر وصفية ووظيفية، مما يعني أن المطورين الآخرين يمكنهم فهم عنوان URL أثناء فهم ما هو المقصود به.
أخيرًا، يمكن أن تكون معلمات المسار متداخلة لتمثيل هيكل هرمي ضمن نموذج موارد واجهة برمجة التطبيقات، وبالتالي يمكنك الوصول إلى الموارد ضمن مجموعات متداخلة. يمكنك التفكير في الأمر على أنه دخول إلى مجلدات ضمن مجلدات للوصول إلى ملف واحد.
ما هي معلمات الاستعلام؟
لدى معلمات الاستعلام أسماء أخرى - معلمات URL أو سلاسل استعلام. إنها معلومات إضافية مرفقة بـ URL بعد علامة استفهام ?.
تأتي معلمات الاستعلام في أزواج مفتاح-قيمة، مفصولة بعلامة & &. تشير معلمات الاستعلام إلى تعليمات اختيارية مصممة لتعديل سلوك طلب واجهة برمجة التطبيقات دون تغيير المورد الأساسي.
أمثلة على معلمات الاستعلام
/users?sort=name&limit=10 هو مثال URL يتكون من منطقتين استعلام، sort و limit.
أزواج المفتاح-القيمة الموجودة في هذا المثال هي sort=name و limit=10.
لماذا تستخدم معلمات الاستعلام؟
مقارنةً بمعلمات المسار، تُستخدم معلمات الاستعلام أكثر من حيث وظائفها.
يمكن أن تعدل معلمات الاستعلام سلوك طلب واجهة برمجة التطبيقات عن طريق إضافة مزيد من المعلومات، مثل في عمليات:
- التصفية: تصفية النتائج بناءً على معايير محددة (على سبيل المثال،
?category=electronics). - الترتيب: ترتيب النتائج بناءً على معايير محددة (على سبيل المثال،
?sort=price,desc). - التقسيم: استرجاع النتائج في قطع أصغر لتحسين الأداء (على سبيل المثال،
?page=2&per_page=20). - البحث: البحث عن موارد معينة بناءً على كلمات مفتاحية (على سبيل المثال،
?q=books).
معلمات المسار مقابل معلمات الاستعلام - جدول
| الميزة | معلمة المسار | معلمة الاستعلام |
|---|---|---|
| الموقع | مضمنة في مسار URL ({id}) |
مرفق بعد '?' (?sort=name&limit=10) |
| الهدف | تحديد موارد معينة | تعديل سلوك الطلب (تصفية، ترتيب، إلخ) |
| إلزامية | نعم | لا |
| الأمان | أقل أمانًا (مرئي في URL) | أكثر أمانًا قليلاً (مفصول عن مسار URL) |
| قابلية القراءة | تحسن قابلية القراءة | يمكن أن تقلل من قابلية القراءة |
| الهيكلية | يمكن أن تكون متداخلة | غير مناسبة للهيكلية |
أداة تطوير واجهة برمجة التطبيقات الشاملة والقوية لعام 2024 - Apidog
Apidog هي منصة شاملة لتطوير واجهات برمجة التطبيقات تسهل المواصفات المختلفة والتعديلات لدورة حياة كاملة لواجهة برمجة التطبيقات. يمكن للمستخدمين بناء، اختبار، تصحيح، توثيق، وتقليد واجهات برمجة التطبيقات جميعها داخل برنامج Apidog.
Apidog هي منصة ممتازة لأولئك الذين يقدرون واجهة مستخدم بسيطة ولكن بديهية. إذا كنت تخطط للتعرف على معلمات المسار والاستعلام. في هذه الحالة، يمكن أن توضح لك Apidog بوضوح كيفية استيراد REST API أو SOAP API وتتيح لك تعديلها.
استيراد ملفات واجهة برمجة التطبيقات الخاصة بك إلى Apidog
لمعرفة كيف يتم تضمين المعلمات في عناوين URL لواجهة برمجة التطبيقات، ستحتاج إلى استيراد واجهة برمجة التطبيقات إلى Apidog.
اختر نوع الملف المناسب الذي يتوافق مع ملف واجهة برمجة التطبيقات الخاص بك. إذا لم تتمكن من العثور على نوع الملف الدقيق، اسحب الملف إلى الجزء السفلي من النافذة، كما هو موضح في الصورة أعلاه.
اختبار نقاط نهاية واجهة برمجة التطبيقات (أو عناوين URL لواجهة برمجة التطبيقات) باستخدام Apidog
بمجرد أن تقوم باستيراد واجهة برمجة التطبيقات بنجاح، يمكنك اختبارها عن طريق إرسال طلب باستخدام Apidog.
اختر أحد طلبات واجهة برمجة التطبيقات الخاصة بك المتوفرة على الجانب الأيمن من الشاشة، كما هو موضح في السهم 1.
ثم، يمكنك إرسال الطلب من خلال النقر على الزر المعروض في السهم 2، ولكن تأكد من أنك قد اخترت البيئة الصحيحة أو قمت بتضمين عنوان URL الصحيح لطلب واجهة برمجة التطبيقات.
أخيرًا، توجه إلى قسم الاستجابة لرؤية الاستجابة التي تم تلقيها بعد إرسال الطلب، وتحقق مما إذا كانت هي نفسها ما هو متوقع.
إضافة المعلمات إلى عنوان URL لواجهة برمجة التطبيقات على Apidog
يمكنك إضافة معلماتك الخاصة إلى عنوان URL لواجهة برمجة التطبيقات من خلال النقر على رأس Params كما هو موضح في الصورة. كن حذرًا إذا كنت ستضيف معلمة، تأكد من الالتزام بالهيكل الصحيح (مثل الأقواس المعوجة {} لمعلمات المسار والرموز المحددة &, ? و = لمجموعة الاستعلام).
الخلاصة
المعلمات هي متغيرات مفيدة للغاية للمطورين لأنها يمكن أن تحدد موارد معينة من مجموعة ضخمة. من خلال استخدام إما معلمات المسار أو الاستعلام، لم تكن عملية الحصول على وتحديث وتصفية موارد معينة من قاعدة بيانات بهذه السهولة من قبل. على الرغم من أنها تبدو متشابهة جدًا، إلا أن معلمة المسار لا تشبه في هيكلها معلمة الاستعلام. ومع ذلك، من الضروري فهم الرموز المختلفة المستخدمة في كلا السيناريوهين والتنسيقات المختلفة التي تعرضها كلا المعلمتين.
Apidog هي منصة شاملة لتطوير واجهات برمجة التطبيقات يمكن أن تستورد أنواعًا مختلفة من ملفات واجهة برمجة التطبيقات. إنها أداة واجهة برمجة تطبيقات رائعة توفر العديد من الخدمات الضرورية المتعلقة بتطوير واجهة برمجة التطبيقات. مع الوظائف التي تتيح للمستخدمين بناء وتخيل وتوثيق واختبار واجهات برمجة التطبيقات، فهي بالتأكيد أداة واجهة برمجة تطبيقات قوية بخلاف Postman وSwaggerHub.