Co jsou API Resources?

Question

Accepted Answer

**API Resources** jsou transformační třídy, které řídí, jak se Eloquent modely (a kolekce) **serializují do JSON** pro API odpovědi. Umožňují vám přesně formovat výstup API — vybrat, která pole vystavit, přejmenovat je, formátovat hodnoty a zahrnout související data — oddělíte tak API reprezentaci od struktury databáze.

## Problém: vystavování surových modelů

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

## Řešení: 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()` zdroje definuje přesný tvar JSON — říkáte, která pole se objeví, přejmenováváte a formátujete je a zahrnujete související resources. Citlivá pole se prostě neuvádějí.

## Podmíněná a vnořená 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
];
```

## Proč to je důležité

API Resources jsou důležité pro vytváření dobře navržených, bezpečných API v Laravel — poskytují vám přesnou kontrolu nad výstupem JSON, což je důležité jak z hlediska **bezpečnosti**, tak z hlediska návrhu API.

Nejkritičnějším přínosem je **prevence úniků dat**: vrácení Eloquent modelů přímo vystavuje všechny jejich sloupce (potenciálně včetně hashů hesel, interních příznaků nebo jiných citlivých dat — vážná zranitelnost), zatímco API Resources vám umožňují explicitně vybrat, která pole vystavit, a zajistit, aby se citlivá data nikdy nedostala ke klientům.

Beyond bezpečnosti umožňují čisté navržení API **oddělením API reprezentace od schématu databáze** — můžete přejmenovat pole, formátovat hodnoty (data, booleany), strukturovat vnořená/související data a podmíněně zahrnout pole na základě oprávnění, vše v dedikované transformační třídě.

To udržuje smlouvu API stabilní a záměrnou spíše než spojenou s vnitřní strukturou tabulky.

Porozumění API Resources — jak formují výstup JSON, bezpečnostní prospěch explicitní kontroly polí a funkce jako podmíněná pole a vnořené zdroje — je důležité vědomosti pro vytváření profesionálních Laravel API, protože vystavování surových modelů je jak nezabezpečené, tak špatný návrh.

Jako REST/JSON API jsou primárním použitím Laravel v dnešní době a kontrola tvaru odpovědi (bezpečně a čistě) je běžné, důležité požadavky, API Resources jsou často používaný, cenný nástroj, který odlišuje dobře vytvořená, bezpečná API od těch, která úniky dat nebo jejich výstup těsně spjatý s databází.