Czym są API Resources?

Question

Accepted Answer

**API Resources** to klasy transformacji, które kontrolują sposób **serializacji modeli Eloquent (i kolekcji) do JSON** dla odpowiedzi API. Pozwalają ci precyzyjnie kształtować dane wyjściowe API — wybierając które pola udostępnić, je przełączać, formatować wartości i dołączać powiązane dane — oddzielając reprezentację API od struktury bazy danych.

## Problem: eksponowanie surowych modeli

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

## Rozwiązanie: 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()` zasobu definiuje dokładny kształt JSON — ty kontrolujesz które pola się pojawiają, przełączasz je i formatujesz oraz dołączasz powiązane zasoby. Poufne pola po prostu nie są uwzględniane.

## Dane warunkowe i zagnieżdżone

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

## Dlaczego to ważne

API Resources są ważne dla budowania dobrze zaprojektowanych, bezpiecznych API w Laravel — dają ci precyzyjną kontrolę nad wyjściem JSON, co ma znaczenie zarówno dla **bezpieczeństwa** jak i projektowania API.

Najkrytyczniejszą korzyścią jest **zapobieganie wyciekom danych**: bezpośrednie zwracanie modeli Eloquent ekspponuje wszystkie ich kolumny (potencjalnie włączając hasze haseł, wewnętrzne flagi czy inne poufne dane — poważna luka bezpieczeństwa), podczas gdy API Resources pozwalają ci jawnie wybrać które pola udostępnić, zapewniając że poufne dane nigdy nie dotrą do klientów.

Poza bezpieczeństwem, umożliwiają czyste projektowanie API poprzez **oddzielenie reprezentacji API od schematu bazy danych** — możesz przełączać nazwy pól, formatować wartości (daty, wartości logiczne), strukturyzować zagnieżdżone/powiązane dane, i warunkowo dołączać pola na podstawie uprawnień, wszystko w dedykowanej klasie transformacji.

To utrzymuje kontrakt API stabilny i celowy, a nie sprzężony do wewnętrznej struktury tabeli.

Zrozumienie API Resources — jak kształtują wyjście JSON, korzyści bezpieczeństwa wynikające z jawnej kontroli pól, i funkcji takich jak pola warunkowe i zasoby zagnieżdżone — jest ważną wiedzą dla budowania profesjonalnych API Laravel, ponieważ eksponowanie surowych modeli jest zarówno niebezpieczne jak i słabym projektowaniem.

Ponieważ REST/JSON API są głównym zastosowaniem Laravel dzisiaj, a kontrolowanie kształtu odpowiedzi (bezpiecznie i czyszczę) jest powszechną, ważną potrzebą, API Resources są często używanym, cennym narzędziem, które rozróżnia dobrze zbudowane, bezpieczne API od tych które wyciekają dane lub ciasno sprzęgają ich wyjście z bazą danych.