ما هو الـ API؟ شرح مبسّط مع أمثلة عملية

الـ API (واجهة برمجة التطبيقات) مجموعة قواعد تسمح لبرنامج بأن يطلب من برنامج آخر بيانات أو ينفّذ له مهمة. تطبيق الطقس في جوالك مثلاً لا يقيس الحرارة بنفسه، بل يرسل طلباً إلى API خدمة طقس فيعود إليه التوقع على شكل بيانات. بهذه الطريقة تتحدث التطبيقات والمواقع والخدمات مع بعضها.

باختصار: يرسل التطبيق طلباً (Request) إلى عنوان الـ API، فينفّذ الخادم المطلوب ويعيد رداً (Response)، وغالباً يكون بصيغة JSON.

تشبيه بسيط: النادل في المطعم

تخيّل مطعماً:

• أنت التطبيق الذي يريد شيئاً.
• المطبخ هو الخادم الذي يملك البيانات والمنطق.
• النادل هو الـ API.

أنت لا تدخل المطبخ لتطبخ بنفسك. تختار من قائمة الطعام، فيحمل النادل طلبك إلى المطبخ ويعود إليك بالطبق. وقائمة الطعام تشبه توثيق الـ API (Documentation): تخبرك بما يمكنك طلبه وكيف تطلبه. ويستطيع المطبخ تغيير معداته بالكامل، وما دامت القائمة كما هي، ستطلب بالطريقة نفسها تماماً.

وهذه هي القيمة الحقيقية للـ API: كل طرف يستطيع تغيير تفاصيله الداخلية دون أن يتعطل الطرف الآخر.

كيف يعمل طلب الـ API؟

تعمل أغلب واجهات API على الويب عبر بروتوكول HTTP، وهو نفس البروتوكول الذي يستخدمه متصفحك. ويتكون الطلب عادةً من:

1. العنوان (Endpoint): الرابط الذي تستدعيه، مثل https://api.example.com/weather.
2. الطريقة (Method): ما تريد فعله، مثل GET لقراءة البيانات.
3. المعاملات (Parameters): تفاصيل إضافية، مثل ?city=Riyadh.
4. الترويسات (Headers): معلومات عن الطلب، مثل مفتاح API يعرّف بك.
5. جسم الطلب (Body) أحياناً: بيانات ترسلها، مثلاً عند إنشاء عنصر جديد.

ويرد الخادم بـ رمز حالة (Status Code) يوضح إن كان الطلب نجح، ومعه غالباً بيانات بصيغة JSON، وهي صيغة نصية بسيطة من أسماء وقيم:

{
  "city": "Riyadh",
  "temp": 31,
  "unit": "C"
}

هذا المثال يستخدم API طقس وهمياً على example.com لتوضيح شكل الطلب فقط. العنوان الحقيقي والحقول تختلف حسب الخدمة التي تستخدمها.

أمثلة على واجهات API تستخدمها يومياً

تعتمد على واجهات API مرات كثيرة في اليوم دون أن تنتبه:

• تسجيل الدخول بحساب Google أو Apple في موقع آخر يستخدم واجهات تسجيل الدخول الخاصة بهما.
• الطقس والخرائط داخل التطبيقات تأتي من واجهات API لخدمات الطقس والخرائط.
• الدفع الإلكتروني في المتاجر يمر عادةً عبر API لمزوّد خدمة الدفع.
• مواقع السفر التي تقارن الرحلات والفنادق تجمع الأسعار من واجهات API لمزوّدين كثيرين.
• مزايا الذكاء الاصطناعي في كثير من التطبيقات ترسل نصك إلى نموذج ذكاء اصطناعي عبر API وتعرض لك الجواب.

وحتى موقعك على الأغلب يتحدث مع API: فـ الواجهة الأمامية والخلفية لأي تطبيق ويب تتواصلان من خلاله.

طرق HTTP ورموز الحالة

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

الطريقة	معناها	مثال
GET	قراءة بيانات	جلب قائمة المنتجات
POST	إنشاء شيء جديد	إنشاء طلب شراء جديد
PUT / PATCH	تعديل بيانات موجودة	تغيير عنوان التوصيل
DELETE	حذف بيانات	إزالة عنصر محفوظ

ورموز الحالة تخبرك بما حدث:

الرمز	معناه
200 OK	نجح الطلب
201 Created	تم إنشاء عنصر جديد
400 Bad Request	في طلبك خطأ
401 Unauthorized	بيانات الدخول ناقصة أو غير صحيحة، مثل مفتاح API
404 Not Found	المورد غير موجود
429 Too Many Requests	تجاوزت حد الطلبات، فخفّف السرعة
500 Internal Server Error	حدث خلل في جهة الخادم

قاعدة سريعة: الرموز التي تبدأ بـ 2 تعني النجاح، و4 تعني مشكلة في طلبك، و5 تعني مشكلة في الخادم.

جرّب API حقيقياً في دقيقة واحدة

لدى GitHub واجهة API عامة يمكنك استدعاؤها بدون حساب للمعلومات الأساسية (مع حد محدود من الطلبات في الساعة). افتح الطرفية ونفّذ:

curl https://api.github.com/users/octocat

ستحصل على JSON يصف الحساب التجريبي الخاص بـ GitHub. هذا جزء مختصر منه:

{
  "login": "octocat",
  "name": "The Octocat",
  "html_url": "https://github.com/octocat",
  ...
}

ويمكنك أيضاً لصق الرابط نفسه في شريط عنوان المتصفح لترى الـ JSON الخام.

استدعاء API من الكود

هذا الطلب نفسه بلغة JavaScript، ويمكنك لصقه كما هو في أدوات المطوّر (Console) داخل متصفحك:

const response = await fetch("https://api.github.com/users/octocat");
const user = await response.json();
console.log(user.name);

وبلغة Python باستخدام مكتبة requests الشهيرة (ثبّتها بالأمر pip install requests):

import requests

response = requests.get("https://api.github.com/users/octocat")
user = response.json()
print(user["name"])

كلا المثالين يطبع The Octocat. والنمط دائماً واحد: أرسل طلباً، وتحقق من رمز الحالة، واقرأ الـ JSON. إذا كانت Python جديدة عليك، فابدأ بدليل Python للمبتدئين.

أنواع واجهات API التي ستسمع عنها

• REST: الأسلوب الأكثر انتشاراً، ويعتمد على روابط واضحة لكل مورد وطرق HTTP مثل GET وPOST، وهو ما شرحناه في هذا الدليل.
• GraphQL: ترسل فيه استعلاماً يحدد الحقول التي تريدها بالضبط، فلا تحصل على بيانات زائدة.
• Webhooks: بدلاً من أن تسأل الخادم كل دقيقة "هل حدث جديد؟"، يرسل الخادم طلباً إلى عنوانك تلقائياً عند وقوع حدث، مثل نجاح عملية دفع.
• واجهات المكتبات وأنظمة التشغيل: كلمة API لا تعني الإنترنت دائماً. الدوال التي توفرها مكتبة برمجية أو نظام تشغيل لبرنامجك هي أيضاً API.

وللمبتدئ، يكفي أن يفهم REST جيداً، فأغلب الخدمات تقدّمه وأغلب الشروحات تستخدمه.

مفاتيح API والحفاظ على الأمان

تطلب واجهات API كثيرة مفتاح API، وهو نص سري طويل يعرّف حسابك ويتتبع استخدامك. تعامل معه ككلمة مرور:

• لا تضع مفتاح API في كود الواجهة الأمامية الذي يعمل في المتصفح، فأي شخص يستطيع قراءته هناك. استدعِ الـ API من الخادم (Backend) بدلاً من ذلك.
• لا ترفع المفاتيح إلى Git أبداً. احفظها في متغيرات البيئة أو في ملف .env مذكور داخل .gitignore. يشرح دليلنا Git وGitHub خطوة بخطوة كيف تفعل ذلك.
• احترم حدود الطلبات واحفظ النتائج مؤقتاً (Cache) عندما يمكن، حتى لا تكرر الطلب نفسه مرة بعد مرة.
• ألغِ المفتاح واستبدله فوراً إذا شككت أنه تسرّب.

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