API Resources کیا ہیں؟

Question

Accepted Answer

**API Resources** تبدیلی کی کلاسز ہیں جو کنٹرول کرتی ہیں کہ Eloquent ماڈلز (اور collections) کو API کے جوابات کے لیے **JSON میں کیسے serialize کیا جائے**۔ یہ آپ کو API کی output کو بالکل درست طریقے سے شکل دینے دیتے ہیں — کون سے fields کو ظاہر کرنا ہے، انہیں دوبارہ نام دینا، values کو format کرنا، اور متعلقہ ڈیٹا شامل کرنا — API کی نمائندگی کو database کی ساخت سے الگ کرتے ہوئے۔

## مسئلہ: raw ماڈلز کو expose کرنا

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

## حل: ایک API Resource

```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
```

Resource کا `toArray()` بالکل JSON کی شکل کو متعین کرتا ہے — آپ کنٹرول کرتے ہیں کہ کون سے fields ظاہر ہوں، انہیں دوبارہ نام دیں اور format کریں، اور متعلقہ resources شامل کریں۔ حساس fields کو آسانی سے شامل نہیں کیا جاتا۔

## مشروط اور nested ڈیٹا

```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 Resources Laravel میں اچھی طریقے سے ڈیزائن کیے گئے، محفوظ APIs بنانے کے لیے اہم ہیں — یہ آپ کو JSON output پر بالکل درست کنٹرول دیتے ہیں، جو **security** اور API ڈیزائن دونوں کے لیے اہم ہے۔

سب سے اہم فائدہ **ڈیٹا کی leaks سے بچاؤ** ہے: Eloquent ماڈلز کو براہ راست واپس کرنا ان کے تمام columns کو expose کرتا ہے (ممکنہ طور پر password hashes، internal flags، یا دیگر حساس ڈیٹا شامل ہے — ایک سنگین vulnerability)، جبکہ API Resources آپ کو یقینی طور پر منتخب کرنے دیتے ہیں کہ کون سے fields کو expose کرنا ہے، یقینی بناتے ہوئے کہ حساس ڈیٹا کبھی clients تک نہیں پہنچتا۔

Security سے آگے، یہ **database schema سے API کی نمائندگی کو الگ کرنے** سے صاف API ڈیزائن کو فعال کرتے ہیں — آپ fields کو دوبارہ نام دے سکتے ہیں، values کو format کر سکتے ہیں (dates، booleans)، nested/related ڈیٹا کو منظم کر سکتے ہیں، اور اختیارات کی بنیاد پر مشروط طور پر fields شامل کر سکتے ہیں، سب ایک مختص transformation class میں۔

یہ API کے معاہدے کو مستحکم اور مقصود رکھتا ہے بجائے اس کے کہ یہ اندرونی table کی ساخت سے جڑا ہو۔

API Resources کو سمجھنا — کہ وہ JSON output کو کیسے شکل دیتے ہیں، explicit field کنٹرول کا security فائدہ، اور conditional fields اور nested resources جیسی خصوصیات — پروفیشنل Laravel APIs بنانے کے لیے اہم علم ہے، کیونکہ raw ماڈلز کو expose کرنا نہ تو محفوظ ہے اور نہ ہی اچھی ڈیزائن ہے۔

چونکہ REST/JSON APIs آج Laravel کے بنیادی استعمال ہیں، اور جواب کی شکل کو کنٹرول کرنا (محفوظ اور صاف طریقے سے) ایک عام، اہم ضرورت ہے، API Resources ایک بار بار استعمال ہونے والا، قیمتی tool ہے جو اچھی طریقے سے بنائے گئے، محفوظ APIs کو ان سے الگ کرتا ہے جو ڈیٹا کو leak کرتے ہیں یا اپنی output کو database سے سختی سے جوڑتے ہیں۔