من الصفر إلى REST API عملي: بناء خدمة Node.js بسيطة للمبتدئين

مقدمة: لماذا REST API وهل هذا الدليل مناسب للمبتدئين؟

واجهات برمجة التطبيقات (APIs) من نوع REST تُستخدم لنقل البيانات بين الخوادم والتطبيقات بطريقة موحَّدة وبسيطة. هذا الدليل العملي موجه للمبتدئين الذين يريدون بناء خدمة REST API صغيرة باستخدام Node.js وExpress. سنغطي إعداد المشروع، كتابة نقاط النهاية الأساسية (CRUD)، اختبار الخدمة محلياً، وبعض النصائح البسيطة للأمان والنشر.

ملاحظة تقنية مهمة: سنعتمد في الأمثلة على إصدار Node.js المُناسب للإنتاج. اعتباراً من تحديثات نهاية أكتوبر 2025، خط إصدار Node.js 24 أصبح في وضع LTS (دعم طويل الأمد)، لذا من الأفضل استخدام إصدار LTS حديث في مشاريع الإنتاج.

المتطلبات والمفاهيم الأساسية

• بيئة عمل: نظام تشغيل (Windows/macOS/Linux)، Node.js مثبت وnpm (أو pnpm/ yarn حسب تفضيلك).
• إطار العمل: Express.js لإنشاء مسارات وخدمات HTTP — الإصدار 5 أصبح شائعًا كخطٍّ حديث ويُوصى بالاطلاع على ملاحظات الإصدار قبل الترقية.
• أدوات اختبار: curl أو HTTP client مثل Postman / Insomnia.

تثبيت Node.js وبدء المشروع

1. تأكد من تثبيت Node.js: للتحقق نفذ node -v وnpm -v.
2. أنشئ مجلد المشروع وابدأ npm:

mkdir my-rest-api
cd my-rest-api
npm init -y

ثم نثبت Express وأدوات مفيدة صغيرة:

npm install express
# اختياري: تثبيت nodemon للتطوير التلقائي
npm install --save-dev nodemon

بناء API بسيط: مثال عملي (ملف واحد)

في هذا المثال سنبني خدمة بسيطة لإدارة عناصر (items) في ذاكرة مؤقتة (array) — مناسبة للتعلّم لكنها ليست للتخزين الدائم.

1) ملف التطبيق الرئيسي index.js

const express = require('express');
const app = express();
const port = process.env.PORT || 3000;

// متوسّط لمعالجة JSON
app.use(express.json());

// بيانات في الذاكرة كمثال
let items = [
  { id: 1, name: 'Item One' },
  { id: 2, name: 'Item Two' }
];

// الحصول على جميع العناصر
app.get('/api/items', (req, res) => {
  res.json(items);
});

// الحصول على عنصر بحسب id
app.get('/api/items/:id', (req, res) => {
  const id = Number(req.params.id);
  const item = items.find(i => i.id === id);
  if (!item) return res.status(404).json({ message: 'Not found' });
  res.json(item);
});

// إنشاء عنصر جديد
app.post('/api/items', (req, res) => {
  const { name } = req.body;
  if (!name) return res.status(400).json({ message: 'Name required' });
  const newItem = { id: items.length ? items[items.length - 1].id + 1 : 1, name };
  items.push(newItem);
  res.status(201).json(newItem);
});

// تحديث عنصر
app.put('/api/items/:id', (req, res) => {
  const id = Number(req.params.id);
  const { name } = req.body;
  const idx = items.findIndex(i => i.id === id);
  if (idx === -1) return res.status(404).json({ message: 'Not found' });
  items[idx].name = name || items[idx].name;
  res.json(items[idx]);
});

// حذف عنصر
app.delete('/api/items/:id', (req, res) => {
  const id = Number(req.params.id);
  items = items.filter(i => i.id !== id);
  res.status(204).end();
});

app.listen(port, () => console.log(`Server running on http://localhost:${port}`));

تشغيل الخادم

لتشغيل في بيئة التطوير مع nodemon:

npx nodemon index.js
# أو
node index.js

اختبار نقاط النهاية وأمثلة curl

بعد تشغيل الخادم، جرّب هذه الطلبات البسيطة:

• جلب جميع العناصر: curl http://localhost:3000/api/items
• جلب عنصر محدد: curl http://localhost:3000/api/items/1
• إنشاء عنصر جديد: curl -X POST -H "Content-Type: application/json" -d '{"name":"NewItem"}' http://localhost:3000/api/items
• تحديث: curl -X PUT -H "Content-Type: application/json" -d '{"name":"Updated"}' http://localhost:3000/api/items/2
• حذف: curl -X DELETE http://localhost:3000/api/items/2

يمكنك استخدام أدوات رسومية مثل Postman أو Insomnia لتجربة الطلبات بسهولة، وفحص رؤوس الاستجابة (headers) وحالة (status) الرد.

نصائح عملية للنشر والأمان (موجز)

• لا تستخدم التخزين في الذاكرة للإنتاج — استخدم قاعدة بيانات مناسبة (Postgres, MongoDB, SQLite حسب الحاجة).
• أضف التحقق من الإدخال (validation) باستخدام مكتبات مثل Joi أو Zod قبل معالجة البيانات.
• استخدم متغيرات بيئة (env) لإدارة إعدادات مثل منفذ الخادم وسلاسل الاتصال، واحفظها خارج الريبو.
• امنح الوصول عبر HTTPS، وتأكَّد من إدارة رؤوس الأمان (CORS, Helmet) وإعداد حدود (rate limiting) عند الحاجة.

خلاصة سريعة: الكود أعلاه هو نقطة انطلاق ممتازة للتعلّم. بعد أن تتقن الأساسيات، انتقل إلى إضافة طبقة تخزين دائمة، اختبارات وحدات (unit tests)، وتحسينات الأداء أو المصادقة (JWT أو OAuth) حسب متطلبات التطبيق.

مراجع فنية: صفحة إصدارات Node.js الرسمية (لمعرفة إصدار LTS الموصى به) وملاحظات إصدار Express للانتقال إلى v5 عند الحاجة.