Što su API Resources?

Question

Accepted Answer

**API Resources** su transformation klase koje kontroliraju kako se Eloquent modeli (i kolekcije) **serijaliziraju u JSON** za API odgovore. Omogućuju vam da precizno oblikujete API output — odabiranjem koje polje izložiti, preimenovanjem, formatiranjem vrijednosti i uključivanjem povezanih podataka — odvajajući API reprezentaciju od strukture baze podataka.

## Problem: izlaganje raw modela

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

## Rješenje: 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
```

Resourceov `toArray()` definira točno JSON oblik — vi kontrolirate koja polja se pojavljuju, preimenovate i formatirate ih, te uključujete povezane resourse. Osjetljiva polja jednostavno nisu uključena.

## Uvjetni i ugniježđeni podaci

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

## Zašto je to važno

API Resources su važni za izgrađivanje dobro dizajniranih i sigurnih API-ja u Laravelu — daju vam preciznu kontrolu nad JSON outputom, što je važno za **sigurnost** i dizajn API-ja.

Najkritičnija korist je **sprječavanje curenja podataka**: vraćanje Eloquent modela izravno izlaže sve njihove stupce (potencijalno uključujući heše lozinki, interne zastavice ili druge osjetljive podatke — ozbiljna ranjivost), dok API Resources omogućuju vam da eksplicitno odaberete koja polja izložiti, osiguravajući da osjetljivi podaci nikada ne dosegnu klijente.

Osim sigurnosti, omogućuju čist dizajn API-ja **odvajanjem API reprezentacije od sheme baze podataka** — možete preimenovati polja, formatirati vrijednosti (datumi, boolean vrijednosti), strukturirati ugniježđene/povezane podatke i uvjetno uključiti polja na temelju dozvola, sve u dedicirannoj transformation klasi.

Ovo čini API ugovor stabilnim i namjernim umjesto da bude vezan uz internu strukturu tablice.

Razumijevanje API Resources — kako oblikuju JSON output, sigurnosnu korist eksplicitne kontrole polja, te značajke kao što su uvjetna polja i ugniježđeni resources — je važno znanje za izgradnju profesionalnih Laravel API-ja, jer je izlaganje raw modela i nesigurno i loša praksa dizajna.

Budući da su REST/JSON API-ji primarni u Laravelu danas, te kako je kontrola oblika odgovora (sigurno i čisto) česta, važna potreba, API Resources su često korišteni, vrijedni alat koji razlikuje dobro izgrađene, sigurne API-je od onih koji curiju podatke ili čvrsto povezuju svoj output s bazom podataka.