Kaj so API Resources?

Question

Accepted Answer

**API Resources** so transformacijske razrede, ki nadzorujejo, kako se Eloquent modeli (in zbirke) **serijalizirajo v JSON** za odgovore API-ja. Omogočajo vam oblikovanje izhoda API-ja natančno — izbiro polj, ki jih izpostavite, njihovo preimenovanje, oblikovanje vrednosti in vključitev povezanih podatkov — razdvojijo predstavo API-ja od strukture podatkovne baze.

## Problem: izpostavljeni surovi modeli

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

## Rešitev: 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
```

Metoda `toArray()` resursa natančno definira obliko JSON-a — vi kontrolirate, katera polja se pojavijo, jih preimenovete in oblikujete ter vključite povezane resurse. Občutljiva polja se preprosto ne vključijo.

## Pogojna in ugnezdena podatka

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

## Zakaj je to pomembno

API Resources so pomembni za gradnjo dobro zasnovanih, varnih API-jev v Laravel-u — dajejo vam natančen nadzor nad izhodi JSON-a, kar je bistvenega pomena za **varnost** in oblikovanje API-ja.

Najkritičnejša prednost je **preprečevanje puščanja podatkov**: vrnitev Eloquent modelov direktno izpostavi vse njihove stolpce (potencialno vključno s heši gesel, notranjimi zastavicami ali drugimi občutljivi podatki — resna ranljivost), medtem ko API Resources omogočijo eksplicitno izbiro, katera polja se izpostavijo, kar zagotavlja, da občutljivi podatki nikoli ne dosežejo klientov.

Poleg varnosti omogočajo čisto oblikovanje API-ja z **razdvojitvijo predstave API-ja od sheme podatkovne baze** — polja lahko preimenovete, oblikujete vrednosti (datume, logične vrednosti), strukturirate ugnezdene/povezane podatke in pogojno vključite polja na podlagi dovoljenj, vse v namenjeni transformacijski razredu.

To ohranja pogodbo API-ja stabilno in namerno namesto da bi bila povezana z notranjo strukturo tabele.

Razumevanje API Resources — kako oblikujejo izhod JSON-a, koristi varnosti eksplicitnega nadzora polj in funkcije, kot so pogojna polja in ugnezdeni resursi — je pomembno znanje za gradnjo profesionalnih Laravel API-jev, saj je izpostavljanje surovih modelov tako nevarno kot slaba zasnova.

Kakor so REST/JSON API-ji primarni namen Laravel-a danes in kakor je nadzor oblike odziva (varno in čisto) običajna, pomembna potreba, so API Resources pogosto uporabljen, dragocen orodje, ki loči dobro zgrajene, varne API-je od tistih, ki puščajo podatke ali tesno povezujejo svoj izhod s podatkovno bazo.