API Resources ਕੀ ਹਨ?

Question

Accepted Answer

**API Resources** transformation classes ਹਨ ਜੋ ਯੋ Eloquent models (ਅਤੇ collections) ਨੂੰ **JSON ਵਿੱਚ serialize** ਕਰਦੀਆਂ ਹਨ API responses ਲਈ। ਉਹ ਤੁਹਾਨੂੰ API output ਨੂੰ precisely shape ਕਰਨ ਦਿੰਦੀਆਂ ਹਨ — ਚੁਣਦੇ ਹੋ ਕਿ ਕਿਹੜੀਆਂ fields expose ਕਰਨੀਆਂ ਹਨ, ਉਹਨਾਂ ਦਾ ਨਾਂ ਬਦਲਦੇ ਹੋ, values ਨੂੰ format ਕਰਦੇ ਹੋ, ਅਤੇ related data ਸ਼ਾਮਲ ਕਰਦੇ ਹੋ — API representation ਨੂੰ database structure ਤੋਂ decouple ਕਰਦੇ ਹੋ।

## ਸਮੱਸਿਆ: 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 shape ਨਿਰਧਾਰਤ ਕਰਦਾ ਹੈ — ਤੁਸੀਂ ਕੰਟਰੋਲ ਕਰਦੇ ਹੋ ਕਿ ਕਿਹੜੀਆਂ fields ਪ੍ਰਗਟ ਹੁੰਦੀਆਂ ਹਨ, ਉਹਨਾਂ ਦਾ ਨਾਮ ਬਦਲਦੇ ਅਤੇ format ਕਰਦੇ ਹੋ, ਅਤੇ related resources ਸ਼ਾਮਲ ਕਰਦੇ ਹੋ। ਸੰਵੇਦਨਸ਼ੀਲ fields ਸਿਰਫ਼ ਸ਼ਾਮਲ ਨਹੀਂ ਹਨ।

## ਮਾਤਰਾਤਮਕ ਅਤੇ 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 ਵਿੱਚ well-designed, secure APIs ਬਣਾਉਣ ਲਈ ਮਹੱਤਵਪੂਰਨ ਹਨ — ਉਹ ਤੁਹਾਨੂੰ JSON output ਉੱਤੇ precise control ਦਿੰਦੀਆਂ ਹਨ, ਜੋ **security** ਅਤੇ API design ਦੋਵਾਂ ਲਈ ਮਾਇਨੇ ਰੱਖਦਾ ਹੈ।

ਸਭ ਤੋਂ ਮਹੱਤਵਪੂਰਨ ਲਾਭ ਹੈ **data leaks ਨੂੰ ਰੋਕਣਾ**: Eloquent models ਨੂੰ ਸਿੱਧਾ return ਕਰਨਾ ਉਹਨਾਂ ਦੇ ਸਾਰੇ columns ਨੂੰ expose ਕਰਦਾ ਹੈ (ਸੰਭਵ ਤੌਰ ਤੇ password hashes, internal flags, ਜਾਂ ਹੋਰ sensitive data ਸ਼ਾਮਲ — ਇੱਕ ਬਹੁਤ ਗੰਭੀਰ ਵਲਨਰੇਬਿਲਟੀ), ਜਦਕਿ API Resources ਤੁਹਾਨੂੰ explicitly ਚੁਣਨ ਦਿੰਦੇ ਹਨ ਕਿ ਕਿਹੜੀਆਂ fields expose ਕਰਨੀਆਂ ਹਨ, ਯਕੀਨੀ ਬਣਾਉਂਦਾ ਹੈ ਕਿ sensitive data ਕਦੀ clients ਤੱਕ ਨਹੀਂ ਪਹੁੰਚਦਾ।

Security ਤੋਂ ਪਰੇ, ਉਹ clean API design ਨੂੰ **API representation ਨੂੰ database schema ਤੋਂ decouple ਕਰਕੇ** ਸਮਰਥ ਬਣਾਉਂਦੀਆਂ ਹਨ — ਤੁਸੀਂ fields ਦਾ ਨਾਮ ਬਦਲ ਸਕਦੇ ਹੋ, values ਨੂੰ format ਕਰ ਸਕਦੇ ਹੋ (dates, booleans), nested/related data ਨੂੰ structure ਕਰ ਸਕਦੇ ਹੋ, ਅਤੇ conditionally fields ਸ਼ਾਮਲ ਕਰ ਸਕਦੇ ਹੋ permissions ਦੀ ਆਧਾਰ ਤੇ, ਸਭ ਇੱਕ dedicated transformation class ਵਿੱਚ।

ਇਹ API contract ਨੂੰ stable ਅਤੇ intentional ਰੱਖਦਾ ਹੈ internal table structure ਨਾਲ coupled ਹੋਣ ਦੀ ਬਜਾਏ।

API Resources ਨੂੰ ਸਮਝਣਾ — ਕਿ ਉਹ JSON output ਨੂੰ ਕਿਵੇਂ shape ਕਰਦੀਆਂ ਹਨ, explicit field control ਦੁਆਰਾ security ਦਾ ਲਾਭ, ਅਤੇ conditional fields ਅਤੇ nested resources ਵਰਗੀਆਂ features — professional Laravel APIs ਬਣਾਉਣ ਲਈ ਮਹੱਤਵਪੂਰਨ ਜਾਣਕਾਰੀ ਹੈ, ਕਿਉਂਕਿ raw models ਨੂੰ expose ਕਰਨਾ insecure ਵੀ ਹੈ ਅਤੇ ਖਰਾਬ design ਵੀ ਹੈ।

ਜਿਵੇਂ REST/JSON APIs Laravel ਦਾ ਪ੍ਰਾਥਮਿਕ ਉਪਯੋਗ ਹਨ ਅੱਜ, ਅਤੇ ਜਿਵੇਂ response shape ਨੂੰ (safely ਅਤੇ cleanly) ਕੰਟਰੋਲ ਕਰਨਾ ਇੱਕ ਆਮ, ਮਹੱਤਵਪੂਰਨ ਲੋੜ ਹੈ, API Resources ਇੱਕ ਬਾਰ-ਬਾਰ ਵਰਤੀ ਜਾਣ ਵਾਲੀ, ਕੀਮਤੀ tool ਹੈ ਜੋ well-built, secure APIs ਨੂੰ ਉਨ੍ਹਾਂ ਤੋਂ ਵੱਖ ਕਰਦੀ ਹੈ ਜੋ data leak ਕਰਦੇ ਹਨ ਜਾਂ ਜਿਨ੍ਹਾਂ ਦਾ output tightly couple ਹੈ database ਨਾਲ।