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

نقاط نهاية واجهة برمجة التطبيقات

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

على سبيل المثال، قد تحتوي واجهة برمجة التطبيقات على نقاط نهاية مثل:

• /users - استرجاع قائمة المستخدمين
• /users/123 - الحصول على تفاصيل المستخدم ذو الرقم التعريفي 123
• /posts - إنشاء منشور مدونة جديد

تحدد نقاط النهاية هيكل واجهة برمجة التطبيقات والعمليات الممكنة. سوف تقدم واجهات برمجة التطبيقات المصممة بشكل جيد تسميات وهيكل منطقي لنقاط النهاية التي تجمع بين الوظائف ذات الصلة.

طرق طلب HTTP

تستخدم واجهات برمجة التطبيقات طرق طلب HTTP للإشارة إلى الإجراء المرغوب تنفيذه لنقطة نهاية. تشمل الطرق الرئيسية في HTTP:

• GET - استرجاع مورد
• POST - إنشاء مورد جديد
• PUT - تحديث مورد موجود
• DELETE - حذف مورد

من خلال تحديد طريقة HTTP، تشير مكالمات واجهة برمجة التطبيقات إلى ما إذا كانت تقوم بجلب البيانات، أو تعديل البيانات، أو تنفيذ إجراء آخر. هذا يوجه كل من خادم واجهة برمجة التطبيقات والعميل حول نية الطلب.

معلمات الطلب

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

تشمل الأنواع الشائعة من المعلمات:

• سلسلة الاستعلام - تضاف إلى عنوان URL نقطة النهاية مثل /users?status=active
• المسار - تُدرج في مسار نقطة النهاية مثل /users/{id}
• رأس - تُرسل كعناوين مخصصة مثل Authorization
• الجسم - تُرسل في جسم الطلب، غالبًا للطلبات POST/PUT

تمكن المعلمات من أشياء مثل الترقيم، والتصفية، والترتيب، والمزيد.

رؤوس الطلب

بالإضافة إلى رؤوس القياسية مثل Content-Type، يمكن لواجهات برمجة التطبيقات قبول رؤوس مخصصة توفر سياقًا ووظائف إضافية. يمكن استخدام الرؤوس لأشياء مثل:

• المصادقة - إرسال الرموز أو بيانات الاعتماد
• توفير معلومات إصدار واجهة برمجة التطبيقات
• الإشارة إلى تنسيق الاستجابة المطلوب
• إضافة سياق لتحديد المعدلات مثل الرموز

تسهل الرؤوس تمرير البيانات الوصفية لطلب واجهة برمجة التطبيقات دون الحاجة لوضعها في عنوان URL أو الجسم.

جسم الطلب

للطلبات POST و PUT التي تنشئ أو تحديث الموارد، يحتوي الجسم على البيانات نفسها. يمكن تنسيق الجسم في JSON، أو XML، أو تنسيقات أخرى.

يسمح الجسم بإرسال موارد أو مجموعات بيانات كاملة، بدلاً من مجرد معلمات فردية. على سبيل المثال، إرسال كافة تفاصيل منشور مدونة جديد في الجسم.

عميل واجهة برمجة التطبيقات

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

استجابة واجهة برمجة التطبيقات

توفر الاستجابة البيانات المطلوبة أو تأكيد النتيجة. ستحتوي على رموز الحالة، ورؤوس الاستجابة، وعادةً ما تحتوي على بيانات الاستجابة.

تشير رموز الاستجابة الشائعة مثل 200 OK، و404 Not Found، و500 Server Error إلى النتيجة. توفر الرؤوس بيانات وصفية مثل الترقيم. يحتوي الجسم على المعلومات المستردة في JSON، أو XML، أو HTML، أو تنسيقات أخرى.

تجعل الاستجابات المصممة بشكل جيد من السهل على مستهلكي واجهة برمجة التطبيقات التحقق من النتيجة واسترجاع بيانات الاستجابة.

رموز الحالة

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

تتضمن الرموز الشائعة:

• 200 OK - نجح الطلب
• 201 Created - تم إنشاء المورد بنجاح
• 400 Bad Request - طلب غير صحيح
• 404 Not Found - المورد المطلوب غير موجود
• 500 Server Error - خطأ داخلي في الخادم

تجعل هذه الرموز الموحدة من السهل على المطورين التحقق برمجيًا من المشكلات.

المصادقة

تتطلب واجهات برمجة التطبيقات العامة المصادقة لتحديد مطوري التطبيقات وتقييد الوصول. تشمل الطرق الشائعة:

• مفاتيح API - رموز فريدة مخصصة لكل مطور
• OAuth - مصادقة مبنية على الرموز حيث تحصل التطبيقات على وصول محدود
• المصادقة الأساسية - إرسال اسم المستخدم/كلمة المرور مع الطلب

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

التوثيق

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

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

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

يغطي هذا المكونات الرئيسية التي تشكل هيكل واجهة برمجة التطبيقات النموذجي. سوف تتضمن واجهات برمجة التطبيقات المصممة بشكل جيد هذه العناصر بطريقة موحدة تجعل من السهل استخدام واجهة برمجة التطبيقات والاندماج معها.

Apidog: أداتك المثالية لتوثيق واجهة برمجة التطبيقات

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

أبرز ميزات Apidog:

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

ما هي الأنواع الأربعة الرئيسية من واجهة برمجة التطبيقات؟

يمكن تصنيف واجهات برمجة التطبيقات إلى أنواع مختلفة بناءً على من هو المقصود منه استهلاكها:

واجهات برمجة التطبيقات العامة

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

تشمل أمثلة واجهات برمجة التطبيقات العامة:

• واجهة برمجة تطبيقات Twitter - وصول إلى بيانات التغريدات والمستخدمين
• واجهة برمجة تطبيقات Stripe - دمج معالجة المدفوعات

واجهات برمجة تطبيقات الشركاء

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

تشمل الأمثلة:

• واجهات برمجة تطبيقات PayPal لشركاء المنصة
• واجهات برمجة تطبيقات Amazon Marketplace للبائعين

واجهات برمجة التطبيقات الداخلية (الواجهات الخاصة)

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

تشمل الأمثلة:

• واجهات برمجة تطبيقات نظام الموارد البشرية لاستخدامها من قبل أنظمة الرواتب
• واجهات برمجة التطبيقات الخاصة بالمخزون لتطبيقات المستودعات الداخلية
• واجهات برمجة التطبيقات الخاصة بتحليلات البيانات لوحات تقارير داخلية

واجهات برمجة التطبيقات المركبة

تُعد واجهات برمجة التطبيقات المركبة، المعروفة أيضًا باسم الواجهات المخصصة، مcreated by combining various other APIs. They serve as a wrapper around multiple APIs to provide a single, unified interface. Composite APIs are useful when a specific function requires data from multiple sources or when you need to simplify complex interactions.

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

كيف تعمل واجهات برمجة التطبيقات؟

توفر واجهات برمجة التطبيقات وسيلة مركزة للتواصل ومشاركة البيانات بين التطبيقات البرمجية المختلفة. نوصي بشدة باختبار واجهة برمجة التطبيقات باستخدام Apidog.

تعمل التفاعلات عادةً كما يلي:

مثال: واجهة برمجة تطبيقات الطقس

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

1. الطلب: يقوم تطبيقك بإرسال طلب HTTP إلى خادم واجهة برمجة تطبيقات الطقس، بما في ذلك الموقع الذي تريد معلومات الطقس عنه. على سبيل المثال، قد ترسل طلبًا مثل هذا:

GET https://api.weather.com/current?location=NewYork

2. المعالجة: يتلقى خادم واجهة برمجة تطبيقات الطقس الطلب، ويستخرج معامل الموقع "NewYork"، ويبحث عن معلومات الطقس الحالي لنيويورك في قاعدة بياناته.

3. الاستجابة: ثم يقوم الخادم بتنسيق بيانات الطقس في استجابة JSON، مثل هذه:

{
  "location": "نيويورك",
  "temperature": "72°F",
  "conditions": "غائم جزئيًا"
}

4. الإرسال: يرسل هذه الاستجابة JSON مرة أخرى إلى تطبيقك.

5. معالجة الجانب العميل: يتلقى تطبيق الطقس الخاص بك استجابة JSON، ويستخرج بيانات الطقس، ويعرضها للمستخدم. على سبيل المثال، قد يظهر "نيويورك: 72°F، غائم جزئيًا" على الشاشة.