مقدمة إلى واجهات برمجة التطبيقات (APIs) وبروتوكول HTTP

1. ما هي واجهة برمجة التطبيقات (API)؟ تشبيه النادل

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

كيف تطلب طعامك؟ لا يمكنك اقتحام المطبخ والصراخ بطلبك؛ فهذا سيسبب فوضى، كما أنك لا تعرف "لغة المطبخ". هنا يأتي دور النادل.

النادل هو الوسيط المثالي. هو واجهة برمجة التطبيقات (API).

• يقدم لك قائمة طعام محددة (هذا هو توثيق الـ API الذي يخبرك بما يمكنك طلبه).
• يأخذ طلبك المنظم (هذا هو الطلب - Request الذي ترسله).
• يذهب إلى المطبخ ويوصل طلبك "بلغتهم" الخاصة.
• يعود لك بالطبق جاهزاً ومنسقاً (هذه هي الاستجابة - Response التي تستقبلها).

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

2. كيف يتواصل "النادل"؟ بروتوكول HTTP

حسناً، فهمنا أن الـ API هو الوسيط. لكن ما هي اللغة أو القواعد التي يستخدمها هذا الوسيط للتواصل؟ هذه اللغة هي بروتوكول نقل النص التشعبي (HTTP - Hypertext Transfer Protocol).

فكر في HTTP على أنه "خدمة البريد" للإنترنت. إنه مجموعة القواعد التي تضمن وصول طلبك (رسالتك) إلى الخادم الصحيح، وفهم الخادم لما تريده، ثم وصول رده إليك بشكل سليم.

جوهر عمل HTTP بسيط للغاية ويقوم على دورة الطلب والاستجابة (Request-Response Cycle):

1. العميل (Client): برنامجك، يرسل طلب HTTP.
2. الخادم (Server): الخدمة التي تتواصل معها، تستقبل الطلب وتعالجه.
3. الخادم (Server): يرسل استجابة HTTP مرة أخرى إلى العميل.

3. تشريح محادثة HTTP

دعنا نتعمق قليلاً في مكونات هذه "المحادثة" بين العميل والخادم.

أ. الطلب (The Request)

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

1. الرابط (URL) ونقطة النهاية (Endpoint): هذا هو العنوان الدقيق الذي ترسله إليه. تماماً كما أن للمطعم عنوان، فإن لكل وظيفة داخل الـ API "نقطة نهاية" خاصة بها.

   • https://api.weather.com/v1/current?city=Riyadh
   • هنا، /v1/current هي نقطة النهاية المسؤولة عن إعطاء الطقس الحالي.

2. الفعل (HTTP Method/Verb): يحدد نية طلبك. الأفعال الأكثر شيوعاً هي:

   • GET: "أحضر لي". يستخدم لجلب البيانات (مثل طلب حالة الطقس).
   • POST: "خذ هذا وأنشئ شيئاً جديداً". يستخدم لإرسال بيانات لإنشاء مورد جديد (مثل نشر تغريدة جديدة أو تسجيل مستخدم جديد).
   • PUT / PATCH: "خذ هذا وعدّل شيئاً موجوداً".
   • DELETE: "احذف هذا".

3. الترويسات (Headers): معلومات إضافية تصف الطلب. مثل ملاحظات إضافية للنادل.

   • Accept-Language: ar: "أفضل أن تكون الاستجابة باللغة العربية".
   • Authorization: Bearer <API_KEY>: "هذه هي بطاقة عضويتي السرية (مفتاح الـ API) التي تثبت أنني مصرح لي بالطلب". سنتحدث عن مفاتيح API لاحقاً.

4. المتن (Body): "محتوى الرسالة" نفسه. يستخدم بشكل أساسي مع طلبات POST و PUT لإرسال البيانات. على سبيل المثال، عند إنشاء مستخدم جديد، ستحتوي "المتن" على بيانات المستخدم (اسمه، بريده الإلكتروني، إلخ) بتنسيق JSON.

ب. الاستجابة (The Response)

عندما يرد الخادم، تكون استجابته منظمة أيضاً:

1. رمز الحالة (Status Code): رقم من ثلاث خانات يخبرك بنتيجة طلبك بسرعة.

   • 2xx (نجاح):
     • 200 OK: "تفضل، هذا هو طلبك".
   • 4xx (خطأ من العميل):
     • 401 Unauthorized: "ليس لديك الصلاحية للقيام بهذا الطلب".
     • 404 Not Found: "لم أجد ما طلبته. العنوان (نقطة النهاية) غير صحيح".
   • 5xx (خطأ من الخادم):
     • 500 Internal Server Error: "حدث خطأ في المطبخ! حاول مرة أخرى لاحقاً".

2. المتن (Body): البيانات الفعلية التي طلبتها، وعادةً ما تكون بتنسيق JSON الذي تدربنا عليه في الدرس السابق!

ملخص الدرس وأهم النقاط

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

أهم النقاط التي استخلصناها:

• API هو الوسيط (النادل) الذي يسمح للبرامج بالتحدث مع بعضها البعض بشكل منظم وآمن.
• HTTP هو البروتوكول (لغة التواصل) الذي يستخدمه الـ API، ويعتمد على دورة طلب واستجابة.
• الطلب (Request) يتكون من: رابط (URL)، وفعل (Method) مثل GET أو POST، وترويسات (Headers)، وأحياناً متن (Body).
• الاستجابة (Response) تتكون من: رمز حالة (Status Code) يوضح النتيجة، ومتن (Body) يحتوي على البيانات المطلوبة (غالباً بتنسيق JSON).

ما التالي؟

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