Kas yra API resursai?

Question

Accepted Answer

**API resursai** yra transformacijos klasės, kurios kontroliuoja, kaip Eloquent modeliai (ir jų kolekcijos) yra **serializuojami į JSON** API atsakymuose. Jie leidžia tiksliai formavoti API išvestį — pasirinkti, kurie laukai būtų rodomi, pervardinti juos, formatuoti reikšmes ir įtraukti susijusius duomenis — atsiskiriant nuo duomenų bazės struktūros.

## Problema: gryni modeliai

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

## Sprendimas: API resursas

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

Resorso `toArray()` metodas apibrėžia tikslią JSON formą — jūs kontroliuojate, kurie laukai pasirodo, pervardinate ir formatuojate juos, bei įtraukiate susijusius resursus. Jautrūs laukai tiesiog nėra įtraukiami.

## Sąlyginiai ir įdėti duomenys

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

## Kodėl tai svarbu

API resursai yra svarbūs norint sukurti gerai suprojektuotus, saugius API Laravel aplinkoje — jie suteikia tikslią kontrolę virš JSON išvesties, kuri svarbi tiek **saugumui** tiek API dizainui.

Svarbiausias privalumas yra **duomenų nutekėjimo prevencija**: grąžinus Eloquent modelius tiesiogiai, paviešinami visi jų stulpeliai (potencialiai įskaitant slaptažodžių maišų, vidinius žymeklius ar kitą jautrią informaciją — rimta pasaulio kelyje), tuo tarpu API resursai leidžia jums aiškiai pasirinkti, kurie laukai būtų paviešinti, užtikrinant, kad jautri informacija niekada nepasieks klientų.

Be saugumo, jie leidžia sukurti gražų API dizainą **atsiskyriant API reprezentacijai nuo duomenų bazės schemos** — galite pervardinti laukus, formatuoti reikšmes (datas, boolean reikšmes), struktūruoti įdėtus/susijusius duomenis, ir sąlygiškai įtraukti laukus pagal leidimus, visa tai atliekant dedikuotoje transformacijos klasėje.

Tai užtikrina, kad API sutartis būtų stabili ir sąmoninga, o ne susieta su vidine lentelės struktura.

Supratimas apie API resursus — kaip jie formuoja JSON išvestį, saugumo naudą iš aiškios lauko kontrolės, bei funkcijų kaip sąlyginiai laukai ir įdėti resursai — yra svarbus žinios norint sukurti profesionalius Laravel API, kadangi grynų modelių paviešinimas yra ir nesaugus, ir prastas dizainas.

Kadangi REST/JSON API yra pirminis Laravel naudojimo būdas šiandien, o išvesties formos kontrolė (saugiai ir gražiai) yra įprasta, svarbi poreikis, API resursai yra dažnai naudojamas, vertingas įrankis, kuris išskiria gerai sukurtuosius, saugius API iš tų, kurie nutekdina duomenis arba glaudžiai susieja jų išvestį su duomenų baze.