API Resources क्या हैं?

Question

Accepted Answer

**API Resources** transformation classes हैं जो नियंत्रित करती हैं कि Eloquent models (और collections) को API responses के लिए **JSON में कैसे serialize किया जाए**। वे आपको API output को सटीक रूप से आकार देने देते हैं — कौन से fields expose करने हैं चुनना, उनका नाम बदलना, values format करना, और संबंधित data शामिल करना — API representation को database structure से अलग करते हुए।

## समस्या: raw models को 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 शामिल करें। Sensitive fields बस शामिल नहीं किए जाते।

## Conditional और nested data

```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 design दोनों के लिए मायने रखता है।

सबसे महत्वपूर्ण लाभ **data leaks को रोकना** है: Eloquent models को सीधे लौटाना उनके सभी columns को expose करता है (संभावित रूप से password hashes, internal flags, या अन्य sensitive data सहित — एक गंभीर vulnerability), जबकि API Resources आपको स्पष्ट रूप से चुनने देते हैं कि कौन से fields expose करने हैं, यह सुनिश्चित करते हुए कि sensitive data कभी clients तक न पहुँचे।

Security से परे, वे **API representation को database schema से अलग करके** clean API design सक्षम करते हैं — आप fields का नाम बदल सकते हैं, values format कर सकते हैं (dates, booleans), nested/related data संरचित कर सकते हैं, और permissions के आधार पर conditionally fields शामिल कर सकते हैं, सब एक समर्पित transformation class में।

यह API contract को internal table structure से coupled होने के बजाय stable और intentional रखता है।

API Resources को समझना — वे JSON output को कैसे आकार देते हैं, स्पष्ट field नियंत्रण का security लाभ, और conditional fields तथा nested resources जैसी विशेषताएँ — professional Laravel APIs बनाने के लिए महत्वपूर्ण ज्ञान है, क्योंकि raw models को expose करना असुरक्षित और खराब design दोनों है।

चूँकि REST/JSON APIs आज Laravel का एक प्राथमिक उपयोग हैं, और चूँकि response आकार को नियंत्रित करना (सुरक्षित और clean तरीके से) एक सामान्य, महत्वपूर्ण आवश्यकता है, API Resources एक बार-बार उपयोग किया जाने वाला, मूल्यवान tool है जो अच्छी तरह से बनाए गए, सुरक्षित APIs को उन से अलग करता है जो data leak करते हैं या अपने output को database से tightly couple करते हैं।