ما هي واجهة REST API؟ شرح مبسط للمبتدئين مع أمثلة عملية

بقلم محمد صقر · 2 نوفمبر 2026 · البرمجة وأساسيات التطوير · قراءة نحو 5 دقيقة

كل تطبيق موبايل يعرض لك حسابك، وكل موقع يجلب منتجاتك من قاعدة بيانات، وكل لوحة تحكم تعرض إحصاءاتك، يعتمد على شيء واحد في الخلفية: واجهة برمجة تطبيقات أي API. ومن أشهر أنواعها وأكثرها استخدامًا REST. فهمها ليس رفاهية للمبرمج؛ هو الجسر الذي يربط واجهة المستخدم بالخادم وقاعدة البيانات. وحتى لو لم تكن مبرمجًا وتشتري تطبيقًا أو موقعًا، فمعرفة المفهوم تساعدك على فهم عرض السعر والمواصفات.

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

ما هو الـAPI؟

الـAPI (Application Programming Interface) عقد بين برنامجين: «إن أرسلت لي طلبًا بهذا الشكل فسأرد عليك بهذا الشكل». تخيّل مطعمًا: أنت الزبون (الواجهة)، والنادل هو الـAPI، والمطبخ هو الخادم وقاعدة البيانات. لا تدخل المطبخ؛ تطلب من النادل بقائمة محددة، فيعود إليك بالطبق. والنادل يرفض الطلبات غير الموجودة في القائمة، وهذه حماية.

وما معنى REST؟

REST أسلوب في تصميم الـAPI على الويب يقوم على أفكار بسيطة:

1. الموارد (Resources): كل شيء له عنوان URL، مثل /products و/products/15 و/users/7/orders.
2. أفعال HTTP الموحدة: GET للقراءة وPOST للإنشاء وPUT/PATCH للتعديل وDELETE للحذف.
3. بلا حالة (Stateless): كل طلب يحمل كل ما يحتاجه الخادم لفهمه، فلا يعتمد على طلب سابق.
4. تمثيلات: غالبًا JSON، وهو نص منظم يفهمه كل لغة برمجة.

وهي ليست بروتوكولًا صارمًا بل أسلوب، ولذلك ستجد واجهات «شبه REST» كثيرة. ومرجع بروتوكول HTTP الأساسي هنا: HTTP على MDN.

الأفعال وما تفعله

شكل الطلب والرد

مثال طلب لقراءة منتج:

curl -s https://api.example.com/products/15 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

والرد:

{
  "id": 15,
  "name": "سماعة لاسلكية",
  "price": 899.5,
  "inStock": true,
  "tags": ["صوتيات", "لاسلكي"]
}

وهذا طلب إنشاء:

curl -X POST https://api.example.com/products \
  -H "Content-Type: application/json" \
  -d '{"name":"ماوس","price":250}'

أكواد الحالة: لغة الخادم في الرد

كل رد يحمل كود حالة يخبرك بما حدث. احفظ هذه العائلات:

• 2xx نجاح: 200 OK و201 Created بعد الإنشاء و204 No Content بعد الحذف.
• 3xx تحويل: 301 و304 Not Modified.
• 4xx خطأ من العميل: 400 Bad Request و401 Unauthorized (لم تسجل دخولك) و403 Forbidden (ليس لديك صلاحية) و404 Not Found و422 لبيانات غير صالحة و429 Too Many Requests.
• 5xx خطأ من الخادم: 500 و502 و503.

استخدام الأكواد الصحيحة يجعل الواجهة سهلة الاستهلاك: لا تُرجع 200 مع رسالة «حدث خطأ» داخل الجسم.

استهلاك API من JavaScript

async function getProducts() {
  const res = await fetch('https://api.example.com/products?limit=10');
  if (!res.ok) throw new Error('HTTP ' + res.status);
  return res.json();
}

async function createProduct(data) {
  const res = await fetch('https://api.example.com/products', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data),
  });
  if (!res.ok) throw new Error('فشل الإنشاء: ' + res.status);
  return res.json();
}

لاحظ فحص res.ok قبل قراءة الجسم. وللتفاصيل الكاملة عن fetch راجع HTTP على MDN وتوثيق Fetch على MDN.

بناء API بسيط بـNode.js

import express from 'express';
const app = express();
app.use(express.json());

const products = [{ id: 1, name: 'لابتوب', price: 18000 }];

app.get('/products', (req, res) => res.json(products));

app.get('/products/:id', (req, res) => {
  const p = products.find(x => x.id === Number(req.params.id));
  if (!p) return res.status(404).json({ error: 'غير موجود' });
  res.json(p);
});

app.post('/products', (req, res) => {
  const { name, price } = req.body;
  if (!name || typeof price !== 'number')
    return res.status(422).json({ error: 'بيانات غير صالحة' });
  const p = { id: products.length + 1, name, price };
  products.push(p);
  res.status(201).json(p);
});

app.listen(3000);

هذا يعمل كنموذج تعليمي. في الإنتاج تستبدل المصفوفة بقاعدة بيانات (SQL أم NoSQL) وتضيف مصادقة وتحققًا وتسجيلًا للأخطاء.

المصادقة والحماية

الـAPI بلا حماية باب مفتوح. الأساسيات:

• HTTPS دائمًا حتى لا تُسرق البيانات في الطريق.
• المصادقة (Authentication): من أنت؟ عبر رمز Bearer أو JWT أو جلسات (Cookies) أو OAuth.
• التفويض (Authorization): ماذا يحق لك؟ تحقق من الصلاحيات في كل طلب وعلى مستوى المورد (لا تكتفِ بإخفاء الأزرار في الواجهة).
• التحقق من المدخلات على الخادم دائمًا. لا تثق بما يرسله العميل.
• تحديد المعدل (Rate Limiting) لمنع الإساءة والهجمات.
• عدم كشف تفاصيل الأخطاء الداخلية للعميل.
• إدارة المفاتيح: لا تضع مفاتيح سرية داخل كود الواجهة أو التطبيق؛ تُكشف بسهولة.

القائمة الأشهر للمخاطر في تطبيقات الويب هي OWASP، وقد لخصنا ما يهم أصحاب المواقع في قائمة أمان المواقع وللتطبيقات في أمان واختبار تطبيقات الموبايل.

أفضل ممارسات تصميم REST

1. أسماء الموارد جمع واسم لا فعل: /orders وليس /getOrders.
2. تسلسل واضح: /users/7/orders للطلبات التابعة للمستخدم 7.
3. ترقيم الصفحات (Pagination): ?page=2&limit=20 حتى لا تُرجع آلاف السجلات.
4. الفلترة والترتيب: ?category=phones&sort=-price.
5. إصدارات: /v1/products لتتمكن من التطوير دون كسر التطبيقات القديمة.
6. رسائل أخطاء موحدة بصيغة JSON ثابتة.
7. توثيق بأداة مثل OpenAPI/Swagger ليفهمه فريقك والعملاء.
8. التخزين المؤقت (Cache) لبيانات القراءة الثقيلة، فيخف الحمل وتزيد السرعة.

REST مقابل بدائل

• GraphQL: يطلب العميل الحقول التي يريدها بالضبط. مفيد للتطبيقات المعقدة بواجهات متعددة، لكنه يضيف تعقيدًا.
• gRPC: سريع بين الخدمات الداخلية.
• WebSockets: للتحديث اللحظي (دردشة، تتبع).

للمبتدئ وأغلب المشاريع التجارية يكفي REST ويغطي الحاجة بوضوح.

من الاستخدام في المشاريع الواقعية

في تطبيق موبايل لمتجر: الشاشة الرئيسية تستدعي GET /products، وصفحة المنتج GET /products/:id، والسلة POST /cart/items، والدفع POST /orders. نفس الـAPI يخدم موقع المتجر وتطبيق أندرويد وiOS ولوحة الإدارة، وهذا سبب اعتماد الأنظمة الحديثة على فصل الواجهة عن الخادم. وهذا ما نطبقه في المتاجر وأنظمة الإدارة وتطبيقات الموبايل.

أخطاء شائعة

• إرجاع 200 دائمًا حتى عند الخطأ.
• تنفيذ عمليات تعديل بـGET، فتتأثر بالتخزين المؤقت وتفتح ثغرات.
• عدم التحقق من الصلاحيات (يستطيع المستخدم تعديل بيانات غيره بتغيير الرقم في الرابط).
• ردود ضخمة بلا ترقيم صفحات.
• كشف مفاتيح سرية في كود الواجهة.
• عدم توثيق الواجهة فيضيع الوقت في التخمين.

أسئلة شائعة

أسئلة شائعة

اقرأ أيضاً

مصادر موثوقة للاستزادة

• HTTP على MDN
• Fetch API
• تعلم Node.js
• OWASP Top 10