كيفية استخدام الـ API في التواصل مع الأنظمة المختلفة.

المقدمة: لماذا نحتاج الـ API؟

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

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

في عالم البرمجة، الـ API هي نفس الفكرة. بس بدل الويتر، عندنا قواعد معينة للتواصل.

---

الفصل الأول: فهم الـ API بشكل حقيقي

ما هي الـ API بالضبط؟

الـ API (Application Programming Interface) هي مجموعة من التعليمات والقواعد اللي بتسمح لتطبيقان يتواصل مع بعضهم.

لما تقول “تطبيقان يتواصل”، مقصدك:

• التطبيق الأول بيطلب معلومة معينة
• التطبيق الثاني بيرد عليه بالمعلومة

بس كيف؟ من خلال طلبات محددة على أنماط معروفة.

الفرق بين النظري والعملي

كل يوم أنت بتستخدم الـ API بدون ما تدرك:

• لما تفتح تطبيق الطقس وتشوف درجة الحرارة – التطبيق بيستخدم API من موقع معين لجيب المعلومات
• لما تسجل دخول بـ Facebook في تطبيق ثاني – التطبيق بيستخدم API من Facebook
• لما تشوف أسعار العملات في تطبيقك – بتجيبها من API معين

يعني الـ API موجودة في كل مكان.

---

الفصل الثاني: أنواع الـ API الشهيرة

قبل ما تبدأ تكتب، لازم تعرف ايش هي أشهر أنواع الـ API اللي بتستخدمها يومياً.

REST API (الأشهر والأكثر استخدام)

REST معناه Representational State Transfer. بس في الحقيقة، احنا بنسميها الـ API البسيطة.

REST API بتستخدم HTTP Methods (الطرق المعروفة):

الطريقة	المعنى	الاستخدام
GET	احصل على بيانات	لما بدك تقرأ معلومة
POST	أضف بيانات جديدة	لما بدك تنشئ حاجة جديدة
PUT	عدّل بيانات موجودة	لما بدك تحدث معلومة
DELETE	احذف بيانات	لما بدك تحذف حاجة

مثال عملي:

لما بدك تجيب قائمة المستخدمين من موقع معين:

textGET https://api.example.com/users

الـ API بترد عليك بـ JSON فيه البيانات:

json{
  "users": [
    {
      "id": 1,
      "name": "محمد",
      "email": "mohammad@example.com"
    },
    {
      "id": 2,
      "name": "فاطمة",
      "email": "fatima@example.com"
    }
  ]
}

GraphQL API

هذه أحدث شوية من REST. الفرق إنك بتحدد بالضبط ايش البيانات اللي بدك.

في REST، الـ API بترد عليك بكل البيانات حتى لو ما احتجتها كلها. في GraphQL، أنت بتقول: “بدي بس الأسماء والإيميلات، مش بدي الأرقام.”

بس GraphQL أعقد شوية من REST، فلو ما زلت جديد، ركز على REST أولاً.

WebSocket API

هذه للتواصل الحي والفوري بين التطبيقات. لما بدك اتصال مستمر (زي الدردشة الحية أو التحديثات الفورية).

---

الفصل الثالث: كيفية استخدام REST API عملياً

الآن نروح للجزء اللي فيه كود وحقائق. هون بتفهم كيفية تطبيقها فعلاً.

الخطوة الأولى: فهم هيكل الطلب

أي طلب API (في REST) بيحتوي على:

1. الـ URL: العنوان اللي بتطلب منه
2. الـ Method: GET, POST, PUT, DELETE
3. الـ Headers: معلومات إضافية (مثل Authorization)
4. الـ Body: البيانات اللي بتبعتها (في POST و PUT)

مثال:

textPOST https://api.example.com/users
Content-Type: application/json
Authorization: Bearer token123

{
  "name": "أحمد",
  "email": "ahmed@example.com",
  "age": 25
}

الخطوة الثانية: استخدام الـ API مع JavaScript

هون الجزء الشيق – كيف نكتب الكود فعلاً:

javascript// استخدام fetch API لعمل طلب GET
fetch('https://api.example.com/users')
  .then(response => response.json())
  .then(data => {
    console.log('البيانات اللي جابتها:', data);
  })
  .catch(error => {
    console.log('في مشكلة:', error);
  });

هسع الشرح:

• fetch() – بترسل الطلب للـ API
• .then(response => response.json()) – بتحول الرد لـ JSON
• .then(data => ...) – بتاخد البيانات الفعلية
• .catch(error => ...) – لو في خطأ، بتتعامل معه

عمل طلب POST (إضافة بيانات جديدة)

javascriptfetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token-here'
  },
  body: JSON.stringify({
    name: 'محمود',
    email: 'mahmoud@example.com',
    age: 30
  })
})
  .then(response => response.json())
  .then(data => {
    console.log('المستخدم الجديد:', data);
  })
  .catch(error => {
    console.log('خطأ في الإضافة:', error);
  });

النقاط المهمة هون:

1. method: 'POST' – بتقول للـ API إني بدي أضيف
2. headers – بتبلغ الـ API إن البيانات بـ JSON وإني مرخص
3. body: JSON.stringify() – بتحول البيانات لـ JSON string

استخدام Async/Await (الطريقة الحديثة والأنظف)

كود أعلاه صح، بس في طريقة أنظف:

javascriptasync function addUser() {
  try {
    const response = await fetch('https://api.example.com/users', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer your-token-here'
      },
      body: JSON.stringify({
        name: 'ليلى',
        email: 'leila@example.com'
      })
    });

    const data = await response.json();
    console.log('تم إضافة المستخدم:', data);
  } catch (error) {
    console.log('حدث خطأ:', error);
  }
}

addUser();

هذه الطريقة أسهل قراءة وفهم من الـ .then() chains.

---

الفصل الرابع: التعامل مع الأخطاء والمشاكل الشائعة

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

مشكلة 1: CORS (Cross-Origin Resource Sharing)

هذا أشهر خطأ بتلاقيه:

textAccess to XMLHttpRequest at 'https://api.example.com/users' 
from origin 'http://localhost:3000' has been blocked by CORS policy

إيش المشكلة؟

المتصفح بيمنع الطلبات من موقع لموقع ثاني لأسباب أمنية.

الحل:

• الـ API يجب إنه يسمح لموقعك (يضيفك للـ whitelist)
• أو تستخدم CORS proxy (لكن ما فيها أمان كويس)
• أو تستخدم backend server بينك وبين الـ API

أفضل حل؟ اتفق مع صاحب الـ API إنه يضيف موقعك.

مشكلة 2: رمز الخطأ (Status Code)

كل رد من الـ API بيحتوي على رمز:

الرمز	المعنى	الحل
200	نجح الطلب	كمل
400	في خطأ في البيانات	تحقق من البيانات اللي بتبعتها
401	ما عندك صلاحية	تحقق من الـ token
404	الـ endpoint ما موجود	تحقق من الـ URL
500	خطأ في الـ server	استنى وحاول لاحقاً

طريقة التعامل الصحيحة:

javascriptasync function getUsers() {
  try {
    const response = await fetch('https://api.example.com/users');
    
    if (!response.ok) {
      throw new Error(`الخطأ: ${response.status} - ${response.statusText}`);
    }
    
    const data = await response.json();
    console.log('البيانات:', data);
  } catch (error) {
    console.log('في مشكلة:', error.message);
  }
}

getUsers();

مشكلة 3: Timeout (الانتظار الطويل)

لو الـ API بطيئ جداً:

javascriptasync function getUsersWithTimeout() {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 5000); // 5 ثواني
  
  try {
    const response = await fetch('https://api.example.com/users', {
      signal: controller.signal
    });
    clearTimeout(timeout);
    
    const data = await response.json();
    console.log('البيانات:', data);
  } catch (error) {
    console.log('انتهت المهلة أو في خطأ:', error.message);
  }
}

getUsersWithTimeout();

---

الفصل الخامس: الأمان والـ Authentication

هذا جزء مهم جداً. ما تبدأ تستخدم API بدون ما تفهم الأمان.

الـ API Key (المفتاح البسيط)

أبسط طريقة للتحقق من الهوية:

javascriptfetch('https://api.example.com/weather', {
  headers: {
    'X-API-Key': 'your-api-key-12345'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

ملاحظة مهمة: ما تحط الـ API Key مباشرة في الكود (خاصة لو بتنشر الكود على GitHub). استخدم environment variables:

في ملف .env:

textAPI_KEY=your-secret-key

في الكود:

javascriptconst apiKey = process.env.API_KEY;

fetch('https://api.example.com/weather', {
  headers: {
    'X-API-Key': apiKey
  }
})

الـ Bearer Token

أكثر أماناً:

javascriptconst token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';

fetch('https://api.example.com/users', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})

---

الفصل السادس: أمثلة عملية من الواقع

مثال 1: تطبيق طقس بسيط

تتصل مع API عامة للطقس وتجيب درجة الحرارة:

javascriptasync function getWeather(city) {
  try {
    const response = await fetch(
      `https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=YOUR_API_KEY&units=metric`
    );
    
    if (!response.ok) {
      throw new Error('المدينة غير موجودة');
    }
    
    const data = await response.json();
    console.log(`درجة الحرارة في ${city}: ${data.main.temp}°C`);
    console.log(`الوصف: ${data.weather[0].description}`);
  } catch (error) {
    console.log('خطأ:', error.message);
  }
}

getWeather('Amman');

مثال 2: تطبيق GitHub User Search

تدور عن مستخدم على GitHub وتجيب معلوماته:

javascriptasync function searchGitHubUser(username) {
  try {
    const response = await fetch(`https://api.github.com/users/${username}`);
    
    if (!response.ok) {
      throw new Error('المستخدم غير موجود');
    }
    
    const user = await response.json();
    
    console.log(`الاسم: ${user.name}`);
    console.log(`المستودعات: ${user.public_repos}`);
    console.log(`المتابعين: ${user.followers}`);
    console.log(`الموقع: ${user.location}`);
  } catch (error) {
    console.log('في مشكلة:', error.message);
  }
}

searchGitHubUser('torvalds');

---

الفصل السابع: الخطوات العملية لبدء استخدام أي API

قبل ما تكتب كود، روح هالخطوات:

الخطوة 1: ادرس التوثيق

أي API محترمة عندها documentation واضحة. مثلاً:

• GitHub API: https://docs.github.com/rest
• OpenWeather API: https://openweathermap.org/api
• JSONPlaceholder: https://jsonplaceholder.typicode.com (للتدرب)

اقرأ:

• الـ endpoints المتاحة
• طريقة الـ authentication
• الـ response format

الخطوة 2: جرب في Postman

Postman هي أداة توفر عليك وقت كتير. بدل ما تكتب كود وتخمن، جرب الـ API مباشرة:

1. حمّل Postman
2. اكتب الـ URL والـ method
3. شوف الرد بالضبط
4. لما تتأكد إنه يشتغل، اكتب الكود

الخطوة 3: ابدأ بـ GET

ما تبدأ بـ POST أو DELETE مباشرة. اكتب GET أولاً وتأكد الاتصال يشتغل:

javascriptfetch('https://api.example.com/data')
  .then(res => res.json())
  .then(data => console.log(data));

الخطوة 4: أضيف Error Handling

كل مرة يحصل خطأ، تعلم منه وحسّن الكود.

الخطوة 5: استخدم async/await

اكتب الكود بشكل نظيف قابل للقراءة.

---

الخاتمة: ليس معقداً كما يبدو

أول مرة سمعت عن الـ API، فكرت إنها حاجة للمبرمجين الكبار بس. بس كلما اشتغلت معها، اكتشفت إنها ببساطة طريقة تطبيقان يتكلم مع بعضهم.

الفكرة الأساسية:

1. أنت بتبعت طلب (request)
2. الـ API بترد عليك (response)
3. أنت بتتعامل مع الرد

خطوتك القادمة:

1. اختار API معروفة وآمنة (زي JSONPlaceholder أو GitHub API)
2. حمّل Postman وجرب الـ API مباشرة
3. اكتب كود JavaScript بسيط يتصل فيها
4. طبّق Error Handling
5. استخدم Async/Await

من هون، ابدأ تبني مشاريع حقيقية. كل مشروع بتاخد فيه هيعلمك حاجات جديدة عن الـ APIs.

---

المصادر المفيدة

• MDN Fetch API: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
• JSONPlaceholder – للتدرب: https://jsonplaceholder.typicode.com/
• Postman – أداة التجربة: https://www.postman.com/
• OpenWeatherMap API: https://openweathermap.org/api
• GitHub REST API: https://docs.github.com/rest