ما هي موارد الـ API؟

Question

Accepted Answer

**موارد الـ API** هي فئات تحويل تتحكم في كيفية **تسلسل نماذج Eloquent (والمجموعات) إلى JSON** لاستجابات الـ API. تتيح لك تشكيل مخرجات الـ API بدقة — باختيار الحقول المراد عرضها وإعادة تسميتها وتنسيق القيم وتضمين البيانات ذات الصلة — مما يفصل تمثيل الـ API عن بنية قاعدة البيانات.

## المشكلة: عرض النماذج الخام

```php
// ❌ returning a model directly exposes ALL columns (maybe including sensitive ones)
return User::find($id);   // { id, name, email, password_hash, internal_notes, ... } 😱
```

## الحل: موارد الـ API

```php
<?php
// php artisan make:resource UserResource
class UserResource extends JsonResource {
    public function toArray($request): array {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            // password and internal fields deliberately OMITTED
            'joined' => $this->created_at->toDateString(),   // format a value
            'is_admin' => (bool) $this->is_admin,
            // include related data (conditionally loaded)
            'posts' => PostResource::collection($this->whenLoaded('posts')),
        ];
    }
}
```

```php
// use it in a controller
return new UserResource($user);                  // a single model
return UserResource::collection(User::all());     // a collection
```

تحدد دالة `toArray()` الخاصة بالمورد بالضبط شكل JSON — يمكنك التحكم في الحقول التي تظهر وإعادة تسميتها وتنسيقها وتضمين الموارد ذات الصلة. الحقول الحساسة ببساطة لا تُضمن.

## البيانات الشرطية والمتداخلة

```php
return [
    'id' => $this->id,
    'secret' => $this->when($request->user()->isAdmin(), $this->secret),  // conditional field
    'posts' => PostResource::collection($this->whenLoaded('posts')),       // only if eager-loaded
];
```

## لماذا يهم هذا

موارد الـ API مهمة لبناء واجهات برمجية محصنة وآمنة وفي Laravel — فهي توفر لك التحكم الدقيق في مخرجات JSON، وهذا يهم لكل من **الأمان** وتصميم الـ API.

أهم فائدة هي **منع تسريب البيانات**: إرجاع نماذج Eloquent مباشرة يعرض جميع أعمدتها (قد تتضمن بيانات حساسة مثل تجزئة كلمات المرور أو الأعلام الداخلية أو بيانات حساسة أخرى — وهي ثغرة أمان خطيرة)، في حين أن موارد الـ API تتيح لك اختيار الحقول المراد عرضها بشكل صريح، مما يضمن عدم وصول البيانات الحساسة إلى العملاء.

بعيداً عن الأمان، فهي تمكّن تصميم واجهة برمجية نظيفة من خلال **فصل تمثيل الـ API عن مخطط قاعدة البيانات** — يمكنك إعادة تسمية الحقول وتنسيق القيم (التواريخ والقيم المنطقية) وهيكلة البيانات المتداخلة/ذات الصلة وتضمين الحقول بشكل مشروط بناءً على الصلاحيات، كل ذلك في فئة تحويل مخصصة.

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

فهم موارد الـ API — كيفية تشكيل مخرجات JSON والفائدة الأمنية للتحكم الصريح في الحقول والميزات مثل الحقول الشرطية والموارد المتداخلة — هو معرفة مهمة لبناء واجهات برمجية احترافية في Laravel، لأن عرض النماذج الخام غير آمن وتصميم سيء. نظراً لأن واجهات برمجية REST/JSON هي الاستخدام الأساسي في Laravel اليوم، وبما أن التحكم في شكل الاستجابة (بشكل آمن ونظيف) هو حاجة شائعة ومهمة، فإن موارد الـ API هي أداة مستخدمة بكثرة وقيّمة تميز واجهات برمجية محصنة وآمنة عن تلك التي تسرب البيانات أو تربط مخرجاتها بقوة بقاعدة البيانات.