API Resources के हुन्?

Question

Accepted Answer

**API Resources** Eloquent मोडेलहरू (र कलेक्शनहरू) लाई API प्रतिक्रियाहरूको लागि **JSON मा सीरिएलाइज** कसरी गर्ने भनेर नियन्त्रण गर्ने रूपान्तरण वर्गहरू हुन्। तिनीहरूले तपाईंलाई API आउटपुट सटीकतासाथ आकार दिन दिन्छन् — कुन क्षेत्रहरू खोलिनेछन् भनेर चयन गर्ने, तिनीहरूलाई पुनः नामकरण गर्ने, मानहरू ढाँचा गर्ने, र सम्बन्धित डेटा समावेश गर्ने — API प्रतिनिधित्वलाई डेटाबेस संरचनाबाट अलग गर्ने।

## समस्या: raw मोडेलहरू खोलिनु

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

संसाधनको `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 Resources Laravel मा राम्रो डिजाइन गरिएको, सुरक्षित APIs निर्माण गर्न महत्त्वपूर्ण छन् — तिनीहरूले तपाईंलाई JSON आउटपुटमा सटीक नियन्त्रण दिन्छन्, जुन **सुरक्षा** र API डिजाइन दुवैको लागि महत्त्वपूर्ण छ।

सबै महत्त्वपूर्ण लाभ **डेटा रिस रोकिनु** हो: Eloquent मोडेलहरू सीधै फिर्ता गर्दा तिनीहरूको सबै स्तम्भहरू खोलिन्छन् (सम्भवतः पासवर्ड हेशहरू, आन्तरिक झण्डाहरू, वा अन्य संवेदनशील डेटा समावेश गर्दा — एक गम्भीर कमजोरी), जबकि API Resources ले तपाईंलाई स्पष्ट रूपमा कुन क्षेत्रहरू खोलिनेछन् भनेर चयन गर्न दिन्छ, यो सुनिश्चित गर्दै कि संवेदनशील डेटा कहिले पनि क्लायन्टहरूमा पुग्दैन।

सुरक्षाभन्दा परे, तिनीहरू **API प्रतिनिधित्वलाई डेटाबेस स्कीमाबाट अलग गर्दै** स्वच्छ API डिजाइन सक्षम गर्छन् — तपाई क्षेत्रहरू पुनः नामकरण गर्न सक्नु हुन्छ, मानहरू ढाँचा गर्न सक्नु हुन्छ (मितिहरू, बुलियनहरू), नेस्टेड/सम्बन्धित डेटा संरचना गर्न सक्नु हुन्छ, र अनुमतिहरूको आधारमा सशर्त रूपमा क्षेत्रहरू समावेश गर्न सक्नु हुन्छ, सबै एक समर्पित रूपान्तरण वर्गमा।

यो API अनुबन्धलाई स्थिर र अभिप्रायपूर्ण राखन्छ बजाय आन्तरिक तालिका संरचनामा युग्मित भएको।

API Resources बुझ्नु — तिनीहरू JSON आउटपुट कसरी आकार दिन्छन्, स्पष्ट क्षेत्र नियन्त्रणको सुरक्षा लाभ, र सशर्त क्षेत्रहरू र नेस्टेड संसाधनहरू जस्ता सुविधाहरू — व्यावसायिक Laravel APIs निर्माण गर्न महत्त्वपूर्ण ज्ञान हो, किनभने raw मोडेलहरू खोलिनु असुरक्षित र खराब डिजाइन दुवै हो।

जस्तो REST/JSON APIs आज Laravel को प्राथमिक उपयोग हुन्, र जस्तो प्रतिक्रिया आकार नियन्त्रण गर्नु (सुरक्षित र स्वच्छतापूर्वक) एक सामान्य, महत्त्वपूर्ण आवश्यकता हो, API Resources एक बारम्बार-प्रयोग गरिएको, मूल्यवान उपकरण हो जुन राम्रो-निर्मित, सुरक्षित APIs लाई डेटा रिस वा डेटाबेसमा कडाई से युग्मित आउटपुट भएका बाटिका अलग गर्छ।