API Development Skill

نظرة عامة

إرشادات لبناء واجهات برمجة تطبيقات (REST APIs) قوية، آمنة، وسهلة الاستخدام.

---

تصميم RESTful API

تسمية الموارد (Resource Naming)

• استخدم الأسماء (Nouns) وليس الأفعال (Verbs).
• استخدم الجمع للمجموعات.

GET /users          // جلب قائمة المستخدمين
GET /users/123      // جلب مستخدم محدد
POST /users         // إنشاء مستخدم جديد
PUT /users/123      // تحديث مستخدم بالكامل
PATCH /users/123    // تحديث جزئي لمستخدم
DELETE /users/123   // حذف مستخدم

رموز الحالة (Status Codes)

استخدم رموز HTTP القياسية:

• 200 OK: نجاح الطلب.
• 201 Created: تم إنشاء المورد بنجاح.
• 400 Bad Request: خطأ في المدخلات.
• 401 Unauthorized: غير مسجل الدخول.
• 403 Forbidden: لا تملك صلاحية.
• 404 Not Found: المورد غير موجود.
• 500 Internal Server Error: خطأ في الخادم.

---

المصادقة والتفويض (Authentication & Authorization)

JWT (JSON Web Tokens)

استخدم JWT للمصادقة في التطبيقات الحديثة.

// Middleware للتحقق من التوكن
const authenticate = (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) return res.status(401).json({ message: 'No token provided' });

  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;
    next();
  } catch (err) {
    res.status(401).json({ message: 'Invalid token' });
  }
};

---

التحقق من المدخلات (Validation)

لا تثق أبداً بمدخلات المستخدم. استخدم مكتبات مثل Zod أو Joi.

import { z } from 'zod';

const createUserSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
  name: z.string().min(2)
});

app.post('/users', (req, res) => {
  const result = createUserSchema.safeParse(req.body);
  if (!result.success) {
    return res.status(400).json(result.error);
  }
  // ... إنشاء المستخدم
});

---

معالجة الأخطاء (Error Handling)

استخدم middleware مركزي لمعالجة الأخطاء.

app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({
    success: false,
    message: 'Something went wrong!',
    error: process.env.NODE_ENV === 'development' ? err.message : undefined
  });
});

---

التوثيق (Documentation)

وثّق الـ API باستخدام Swagger/OpenAPI.

/users:
  get:
    summary: Returns a list of users.
    responses:
      200:
        description: A JSON array of user names

---

تحديد المعدل (Rate Limiting)

احمِ الـ API من الهجمات والاستخدام المفرط.

import rateLimit from 'express-rate-limit';

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100 // limit each IP to 100 requests per windowMs
});

app.use(limiter);