في درس الأتمتة سألنا خدمة مجانية عن سعر الدولار، فجاءنا الجواب. لم نفتح موقعًا ولم نقرأ نشرة أسعار، بل سأل برنامج الذكاء الاصطناعي برنامجًا آخر وحصل على الجواب.
هذه الطريقة اسمها API. وهي من أكثر المصطلحات التي ستقابلها في عالم البرمجة، وفهمها يساعدك على فهم الكثير في عالم التقنية.
في هذا الدرس
ما هو API؟
API اختصار لعبارة Application Programming Interface، أي «واجهة برمجة التطبيقات». الاسم طويل، لكن الفكرة بسيطة.
تخيّل أنك جالس في مطعم. أنت لا تدخل المطبخ أو تأخذ الطعام بنفسك. يأتيك نادل: تطلب منه من القائمة، فيذهب إلى المطبخ، ثم يعود إليك بالطبق.
ما هو API؟
API هي الطريقة المتفق عليها التي يطلب بها برنامج شيئًا من برنامج آخر ويستلم الجواب.
- النادل هو الـ API.
- القائمة هي ما يسمح لك الـ API بطلبه، ولا تطلب شيئًا خارجها.
- المطبخ هو الخدمة التي عندها البيانات أو التي تقوم بالعمل.
وكل خدمة لها قائمتها: خدمة أسعار العملات تجيب عن أسعار العملات، وخدمة الطقس تجيب عن الطقس، وخدمة الدفع تنفّذ عمليات الدفع. لا تسأل خدمة الطقس عن الدولار.
كيف يبدو الطلب والجواب؟
الطلب في API عادةً رابط تعرفه، مثل رابط موقع. أما الجواب فليس صفحة جميلة، بل بيانات مرتبة يستطيع البرنامج قراءتها بسهولة.
هذا هو الطلب الذي استخدمناه في درس الأتمتة، وهو سؤال عن أسعار العملات مقابل الدولار:
https://open.er-api.com/v6/latest/USD
وجوابه يشبه هذا (اختصرتُه لتراه بوضوح):
{
"result": "success",
"base_code": "USD",
"rates": {
"JOD": 0.709,
"SAR": 3.75,
"AED": 3.6725
}
}
هذا الشكل اسمه JSON، وهو أشهر شكل تعيد به الـ API بياناتها: أسماء بين علامتي تنصيص، وبجانب كل اسم قيمته. اقرأه كما تقرأ جدولًا:
"JOD": 0.709يعني أن الدولار الواحد يساوي 0.709 دينار أردني."SAR": 3.75يعني أن الدولار الواحد يساوي 3.75 ريال سعودي.
الأرقام التي أمامك تتغيّر، فلا تقلق إن رأيت رقمًا آخر عندما تجرّب.
جرّب بنفسك
لا تحتاج إلى أي برنامج. افتح الرابط في المتصفح:
ستظهر لك صفحة نصية فيها جواب الـ API كما يراه البرنامج: كلمات وأرقام مرتبة. ابحث عن "JOD" و"SAR"، ثم ابحث عن time_next_update_utc. هذا الحقل يخبرك متى ستتحدّث الأسعار، لأن هذه الخدمة تحدّث أرقامها مرة واحدة في اليوم.
ما الذي رأيته؟
لقد أرسلت الآن طلبًا إلى API، وهذا بالضبط ما يفعله أي برنامج حين يسأل خدمة. الفرق أنك قرأت الجواب بعينك، أما البرنامج فيقرأه بسرعة ويستعمله في عمله.
سؤال سريع
في الرابط https://open.er-api.com/v6/latest/USD، ما معنى USD في آخره؟
أظهر الإجابة
هي العملة الأساسية التي تُقاس بها بقية العملات. لو كتبنا EUR مكانها لأتتنا الأسعار مقابل اليورو.
ماذا تعني رموز الاستجابات؟
مع كل جواب يرسل الـ API رمزًا من ثلاثة أرقام يخبرك كيف سار الطلب، من المفيد أن تعرف أشهرها:
| الرمز | المعنى | كالمطعم |
|---|---|---|
| 200 | نجح الطلب وجاءك الجواب | جاءك الطبق |
| 404 | لا شيء في هذا العنوان | طلبت طبقًا ليس في القائمة |
| 401 أو 403 | لا تملك إذنًا أو مفتاحًا صحيحًا | لا يسمحون لك بدخول المطبخ |
| 429 | طلبت مرات كثيرة جدًّا في وقت قصير | النادل يطلب منك أن تنتظر |
| 500 | الخدمة نفسها توقفت | تعطّل شيء في المطبخ |
القاعدة السهلة: الرموز التي تبدأ بـ 2 نجاح، والتي تبدأ بـ 4 خطأ منك أو بالطلب، والتي تبدأ بـ 5 خطأ من جهة الخدمة.
ما هو الويب هوك (Webhook)؟
في الـ API أنت من يسأل. لكن أحيانًا لا تريد أن تسأل كل دقيقة: «هل حدث شيء؟»
تخيّل أنك تنتظر طردًا من متجر. لديك طريقتان:
- أن تتصل بالمتجر كل ساعة: «هل وصل طردي؟» هذه طريقة الـ API.
- أن تعطي المتجر رقمك، فيرسل لك رسالة في اللحظة التي يصل فيها الطرد. هذه طريقة الـ Webhook.
ما هو الويب هوك؟
الويب هوك هو API معكوس: بدل أن تتصل أنت بالخدمة، تتصل الخدمة بك حين يحدث شيء. تعطيها عنوانًا في موقعك أو برنامجك، وهي ترسل إليه رسالة عند الحدث.
مثال حقيقي: عندما يدفع زائر ثمن كتاب عبر باي بال (بوابة دفع)، لا يظل موقع البائع يسأل باي بال كل ثانية: «هل دفع؟». يرسل باي بال بنفسه رسالة إلى عنوان في موقع البائع تقول إن الدفع تمّ، فيعرف الموقع أن عليه إرسال الكتاب.
وفي n8n مُشغِّل اسمه Webhook: ينتظر رسالة من خدمة أخرى، وحين تصل يكمل سير العمل.
سؤال سريع
عندما يصل بريد جديد إلى صندوقك فيظهر إشعار في هاتفك دون أن تفتح التطبيق، هل هذا يشبه API أم Webhook؟
أظهر الإجابة
يشبه Webhook: الخدمة هي التي أخبرتك عند حدوث الشيء، ولم تسأل أنت عن الحدث بنفسك.
أين الذكاء الاصطناعي من هذا كله؟
في كل مرة تكتب سؤالًا في تطبيق ذكاء اصطناعي، يرسل التطبيق سؤالك إلى النموذج عبر API، ثم يعرض لك جوابه. التطبيق هو الزبون، والنموذج هو المطبخ.
وعندما يستخدم الوكيل أداة (وسنعرف الوكلاء في درس لاحق)، فهو يطلب من هذه الأداة عبر API أيضًا. وMCP طريقة موحّدة لتوصيل هذه الطلبات.
وهناك ثلاثة أمور تقابلك مع الـ API كلما استعملتها:
- مفتاح API (API key): كلمة سر للخدمة تثبت أنك صاحب الحساب. لا تشاركه مع أحد ولا ترفعه في كود تنشره على الإنترنت.
- السعر: كثير من الـ API تُحاسب على كل استخدام، وبعضها يحاسب بالتوكن (راجع ما التوكن؟).
- حد الاستخدام: كثير منها يحدّد عدد الطلبات في الساعة، ورمز 429 يخبرك بأنك تجاوزته.
سؤال سريع
ما الشيء الذي يجب ألا تفعله بمفتاح API؟
أظهر الإجابة
ألا تشاركه ولا تضعه في كود منشور على الإنترنت، فمن يملكه يستطيع أن يستخدم حسابك ويزيد تكلفة الاستخدام عليك.
الخلاصة
- API هي طريقة يطلب بها برنامج شيئًا من برنامج آخر، مثل النادل بين الزبون والمطبخ.
- الطلب عادةً رابط، والجواب بيانات JSON مرتبة معها رمز يخبرك كيف سار الطلب.
- Webhook هو API معكوس: الخدمة تتصل بك حين يحدث شيء.
- كل تطبيق ذكاء اصطناعي يستخدم API ليتحدث مع النموذج.