ما هي API Resources في Laravel ولماذا تعد أفضل من إرجاع نماذج Eloquent كـ JSON مباشرة؟

الإجابة المختصرة

تعمل كطبقة تحويل (Transformation Layer) تفصل بنية جداول قاعدة البيانات عن استجابة الـ API، وتمنع تسريب الحقول الحساسة وتوحد تنسيق البيانات.

الشرح

إرجاع $user مباشرة كـ JSON يربط واجهة الـ API بهيكل جدول قاعدة البيانات؛ فأي تعديل في اسم عمود سيكسر تطبيقات الموبايل والعملاء الخارجيين، بالإضافة لخطر تسريب أعمدة حساسة. فئات JsonResource تسمح باختيار الحقول بدقة، وإعادة تسميتها، وتضمين العلاقات المشروطة عبر whenLoaded()، وتنسيق التواريخ بشكل موحد.

مثال بالكود

class UserResource extends JsonResource {
    public function toArray(Request $request): array {
        return [
            'id' => $this->id,
            'fullName' => $this->name,
            'posts' => PostResource::collection($this->whenLoaded('posts')),
        ];
    }
}

أخطاء شائعة

• تحميل العلاقات داخل الـ Resource مباشرة مما يعيد خلق مشكلة N+1، بدلاً من استخدام $this->whenLoaded().

أسئلة متابعة

• كيف تصمم معالج أخطاء مركزي وموحد لاستجابات الـ API في Laravel؟

المصادر

• Laravel docs — Eloquent: API Resources