كيف تصمم REST API جيدة؟ دليل عملي

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

ما الذي يجعل REST API جيدة؟

تصمّم الواجهة القوية حول موارد العمل، وتحترم دلالات HTTP، وتعيد JSON ثابت البنية وأخطاء قابلة للمعالجة، وتحمي البيانات، وتتطور دون كسر العملاء الحاليين.

1. صمّم حول الموارد والأسماء

مثّل مفاهيم مستقرة مثل orders وcustomers وinvoices. استخدم أسماء جمع، وعبّر عن العلاقات بمسارات مثل /orders/42/items بدل /getOrderItems. تجنب التداخل العميق لأنه يصعّب الصيانة والصلاحيات.

GET    /api/v1/orders
POST   /api/v1/orders
GET    /api/v1/orders/42
PATCH  /api/v1/orders/42
DELETE /api/v1/orders/42

2. استخدم طرق HTTP بمعناها الصحيح

GET للقراءة دون تغيير الحالة، وPOST للإنشاء أو العملية غير المتكررة بأمان، وPUT للاستبدال الكامل، وPATCH للتعديل الجزئي، وDELETE للحذف. اتباع RFC 9110 يجعل سلوك العملاء والذاكرة الوسيطة والمراقبة صحيحاً.

3. أعد أكواد حالة دقيقة

استخدم 200 للنجاح، و201 للإنشاء مع ترويسة Location، و204 عندما لا يوجد محتوى. ميّز بين 400 لطلب غير صالح، و401 لغياب المصادقة، و403 لرفض الصلاحية، و404 لعدم وجود المورد، و409 للتعارض، و422 لفشل التحقق، و429 لتجاوز الحد.

4. ثبّت شكل JSON

اختر قاعدة واحدة لأسماء الحقول، والتواريخ، والمبالغ، والقيم الفارغة، وغلاف الاستجابة. استخدم ISO 8601 مع المنطقة الزمنية، ولا تكشف أعمدة قاعدة البيانات تلقائياً؛ فالاستجابة عقد عام.

{
  "data": {
    "id": 42,
    "status": "paid",
    "total": 129.90,
    "currency": "USD"
  }
}

5. اجعل الأخطاء مفيدة

يجب أن يحتوي الخطأ على نوع أو رمز ثابت، وعنوان قصير، والحالة، وشرح آمن، وأخطاء الحقول، ومعرّف للطلب. يقدّم RFC 9457 Problem Details صيغة قياسية.

{
  "type": "https://api.example.com/problems/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "errors": {"email": ["The email field is required."]}
}

6. وحّد القوائم والترقيم

استخدم معاملات واضحة مثل ?status=paid&sort=-created_at&page=2&per_page=25، ووثّق الحقول المسموح تصفيتها وترتيبها، وحدد حجماً أقصى للصفحة. يناسب cursor pagination البيانات الكبيرة والمتغيرة سريعاً.

7. خطط للتوافق والإصدارات

إضافة حقل اختياري أو نقطة نهاية جديدة غالباً آمنة، أما تغيير اسم حقل أو نوعه أو حذف سلوك فهو تغيير كاسر. استخدم استراتيجية واضحة مثل /api/v1، وحدد مدة إيقاف معلنة ودليل ترحيل.

8. اجعل الأمان جزءاً من التصميم

استخدم HTTPS، وصادق العميل، وافحص صلاحية كل عملية على كل مورد. طبّق قوائم سماح للتحقق، وحدود حجم الطلب، وrate limiting، ولا ترجع الأسرار أو stack traces. سجّل الأحداث الأمنية دون تسجيل كلمات المرور أو البيانات الحساسة.

9. التخزين المؤقت والتزامن

للقراءات الآمنة استخدم Cache-Control وETag والطلبات الشرطية. استخدم If-Match أو رقم إصدار لمنع عميل من الكتابة فوق تعديل عميل آخر. وتساعد idempotency keys على إعادة طلبات الدفع أو الإنشاء بأمان.

10. وثّق واختبر

احتفظ بعقد OpenAPI يتضمن أمثلة للنجاح والتحقق والمصادقة وتجاوز الحد. اختبر العقد، وأضف correlation IDs وسجلات منظمة ومقاييس latency والأخطاء وdistributed tracing.

تطبيق REST API نظيفة في Laravel

ينشئ Route::apiResource مسارات CRUD التقليدية، وتوفر Sanctum المصادقة، وتحمي throttle middleware نقاط النهاية.

use App\Http\Controllers\Api\OrderController;
use Illuminate\Support\Facades\Route;

Route::prefix('v1')
    ->middleware(['auth:sanctum', 'throttle:api'])
    ->group(function () {
        Route::apiResource('orders', OrderController::class);
    });

استخدم Form Requests للتحقق والتفويض، وEloquent Policies لصلاحيات الموارد، وAPI Resources للتحكم في عقد JSON. اترك المتحكم لتنظيم HTTP وضع منطق العمل المعقد في services أو actions.

public function show(Order $order): OrderResource
{
    return new OrderResource($order);
}

public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'status' => $this->status,
        'total' => $this->total,
        'currency' => $this->currency,
    ];
}

قائمة مراجعة

• مسارات موارد واضحة ومتوقعة
• طرق HTTP وأكواد حالة صحيحة
• JSON ثابت وأخطاء Problem Details
• تصفية وترتيب وترقيم موثقة
• مصادقة وصلاحيات وتحقق وحدود طلبات
• سياسة توافق وإصدارات
• OpenAPI واختبارات عقد وسجلات ومقاييس

أسئلة شائعة

هل نستخدم الأفعال في المسارات؟

غالباً لا؛ استخدم أسماء الموارد وطرق HTTP. يمكن تمثيل أمر مجال حقيقي مثل POST /orders/42/cancellation كمورد واضح.

ما القاعدة الأهم؟

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