بناء عميل API بسيط: جلب وعرض المهام باستخدام بايثون

📚 مراجعة سريعة: هذا التطبيق العملي مبني على مفهوم برمجي أساسي. راجع الدرس النظري من هنا أولاً.

---

مقدمة افتتاحية: بعد أن تعرفنا نظريًا على مفهوم واجهات برمجة التطبيقات (APIs) وكيفية تبادل البيانات باستخدام صيغة JSON، حان الوقت لنطبق هذه المعرفة عمليًا! في هذا الدرس، سنقوم ببناء برنامج بايثون بسيط يقوم بالاتصال بواجهة برمجة تطبيقات عامة، جلب بيانات مهمة عشوائية، وعرضها بطريقة واضحة ومفهومة. استعد لتطبيق ما تعلمته وتحويل الكود النظري إلى واقع عملي!

الهدف من تطبيقنا العملي

هدفنا هو إنشاء دالة في بايثون تقوم بما يلي:

1. الاتصال بواجهة برمجة تطبيقات خارجية (API).
2. جلب بيانات مهمة (Todo item) من هذه الـAPI.
3. تحليل البيانات المستلمة.
4. طباعة تفاصيل المهمة بشكل منسق على الشاشة.
5. التعامل مع أي أخطاء محتملة أثناء عملية الجلب.

شرح الكود خطوة بخطوة

لنأخذ الكود الذي لدينا ونشرح كل جزء منه بالتفصيل:

1. استيراد المكتبات الضرورية

import urllib.request
import json

• urllib.request: هذه الوحدة هي جزء من مكتبة بايثون القياسية وتُستخدم لفتح عناوين URL (روابط الويب) وقراءة البيانات منها. إنها أداة رائعة لإجراء طلبات HTTP الأساسية.
• json: هذه الوحدة ضرورية للتعامل مع بيانات JSON. تسمح لنا بتحويل نصوص JSON التي نستقبلها من الـAPI إلى كائنات بايثون (مثل القواميس) والعكس.

2. تعريف الدالة fetch_random_todo

def fetch_random_todo():
    # ... محتوى الدالة ...

نضع كل منطق البرنامج داخل دالة اسمها fetch_random_todo. هذا يجعل الكود منظمًا وقابلًا لإعادة الاستخدام.

3. تحديد رابط الـAPI

    url = "https://jsonplaceholder.typicode.com/todos/1"

هنا نُعرف المتغير url الذي يحمل رابط الـAPI الذي نريد الاتصال به. jsonplaceholder.typicode.com هو موقع يوفر واجهات برمجة تطبيقات وهمية (dummy APIs) للاختبار والتجارب، وهو مثالي لأغراض التعلم.

4. الاتصال بالـAPI وجلب البيانات (مع معالجة الأخطاء)

    try:
        with urllib.request.urlopen(url) as response:
            data = json.loads(response.read().decode())
            
            # ... طباعة البيانات ...
            
    except Exception as e:
        print(f"حدث خطأ أثناء جلب البيانات: {e}")

• كتلة try-except: هذه الكتلة حاسمة لأي كود يتفاعل مع الشبكة. إذا حدث أي خطأ (مثل عدم وجود اتصال بالإنترنت، أو رابط غير صحيح، أو مشكلة في الخادم)، فلن يتعطل برنامجنا، بل سيتم التقاط الخطأ وعرض رسالة مفيدة.
• with urllib.request.urlopen(url) as response:: هذه هي الخطوة التي نرسل فيها طلب HTTP إلى الرابط المحدد. عند نجاح الاتصال، يتم تخزين الاستجابة في الكائن response. كلمة with تضمن إغلاق الاتصال بشكل صحيح تلقائيًا.
• response.read().decode(): بعد استلام الاستجابة، نقوم بقراءة محتواها الخام (response.read()) ثم فك ترميزها (.decode()) إلى نص عادي (عادةً باستخدام ترميز UTF-8).
• data = json.loads(...): هنا نستخدم وحدة json لتحويل النص الذي استلمناه (والذي هو بصيغة JSON) إلى قاموس بايثون يمكننا التعامل معه بسهولة.

5. عرض تفاصيل المهمة

            print("=== تفاصيل المهمة المستلمة من الخادم ===")
            print(f"رقم المهمة: {data['id']}")
            print(f"عنوان المهمة: {data['title']}")
            print(f"هل اكتملت؟ {'نعم ✅' if data['completed'] else 'لا ❌'}")

بعد تحويل بيانات JSON إلى قاموس بايثون (المتغير data)، يمكننا الوصول إلى قيم العناصر باستخدام مفاتيحها (مثل data['id']). نستخدم f-strings لتنسيق الإخراج بشكل جميل وواضح. لاحظ كيف نتحقق من قيمة data['completed'] (التي تكون True أو False) لعرض رسالة مناسبة بالعربية مع رمز تعبيري.

6. استدعاء الدالة

fetch_random_todo()

أخيرًا، نقوم باستدعاء الدالة التي عرفناها لتشغيل البرنامج وبدء عملية جلب البيانات.

الكود البرمجي الكامل

إليك الكود كاملاً لسهولة النسخ واللصق:

import urllib.request
import json

def fetch_random_todo():
    # رابط لواجهة برمجة تطبيقات مجانية للتجارب
    url = "https://jsonplaceholder.typicode.com/todos/1"
    
    try:
        # الاتصال بالرابط وقراءة البيانات
        with urllib.request.urlopen(url) as response:
            # تحويل البيانات القادمة إلى قاموس بايثون المقروء
            data = json.loads(response.read().decode())
            
            print("=== تفاصيل المهمة المستلمة من الخادم ===")
            print(f"رقم المهمة: {data['id']}")
            print(f"عنوان المهمة: {data['title']}")
            print(f"هل اكتملت؟ {'نعم ✅' if data['completed'] else 'لا ❌'}")
            
    except Exception as e:
        print(f"حدث خطأ أثناء جلب البيانات: {e}")

fetch_random_todo()

كيفية تشغيل الكود

1. احفظ الكود في ملف بايثون (مثال: api_client.py).
2. افتح سطر الأوامر (Command Prompt أو Terminal).
3. انتقل إلى المجلد الذي حفظت فيه الملف.
4. شغل الكود باستخدام الأمر: python api_client.py

سترى مخرجات البرنامج تعرض تفاصيل المهمة المستلمة من الخادم.

أفكار لتحسين وتطوير المشروع

• جلب مهام عشوائية: بدلاً من جلب المهمة رقم 1 دائمًا، يمكنك جعل رقم المهمة ديناميكيًا (مثل استخدام random.randint()).
• جلب قائمة مهام: يمكنك تغيير الرابط لجلب قائمة كاملة من المهام (مثال: https://jsonplaceholder.typicode.com/todos) ثم تكرار عرضها.
• إضافة معلمات للطلب: تعلم كيفية إرسال معلمات (parameters) مع طلب الـAPI لتصفية البيانات أو طلب أنواع معينة منها.
• استخدام مكتبات أسهل: في المشاريع الكبيرة، يفضل استخدام مكتبات مثل requests التي تجعل التعامل مع الـAPIs أسهل وأكثر قوة من urllib.request.

خاتمة

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