Что такое API Resources?

Question

Accepted Answer

**API Resources** — это классы трансформации, которые управляют тем, как модели Eloquent (и коллекции) **сериализуются в JSON** для ответов API. Они позволяют вам точно формировать выходные данные API — выбирая, какие поля показывать, переименовывая их, форматируя значения и включая связанные данные — отделяя представление API от структуры базы данных.

## Проблема: экспозиция сырых моделей

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

## Решение: 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
```

Метод `toArray()` resource определяет точную форму JSON — вы контролируете, какие поля появляются, переименовываете и форматируете их, и включаете связанные ресурсы. Конфиденциальные поля просто не включаются.

## Условные и вложенные данные

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

## Почему это важно

API Resources важны для создания хорошо спроектированных, безопасных API в Laravel — они дают вам точный контроль над выходом JSON, что имеет значение как для **безопасности**, так и для дизайна API.

Самая критическая выгода — **предотвращение утечек данных**: возврат моделей Eloquent напрямую открывает все их столбцы (потенциально включая хеши паролей, внутренние флаги или другие конфиденциальные данные — серьёзная уязвимость), в то время как API Resources позволяют вам явно выбирать, какие поля показывать, гарантируя, что конфиденциальные данные никогда не достигнут клиентов.

Помимо безопасности, они обеспечивают чистый дизайн API благодаря **отделению представления API от схемы базы данных** — вы можете переименовывать поля, форматировать значения (даты, булевы), структурировать вложенные/связанные данные и условно включать поля на основе прав доступа, всё это в отдельном классе трансформации.

Это делает контракт API стабильным и намеренным, а не связанным с внутренней структурой таблицы.

Понимание API Resources — как они формируют выход JSON, выгода безопасности от явного управления полями и функции вроде условных полей и вложенных ресурсов — это важные знания для создания профессиональных Laravel API, так как экспозиция сырых моделей одновременно небезопасна и плохо спроектирована.

Поскольку REST/JSON API являются основным использованием Laravel сегодня, и поскольку управление формой ответа (безопасно и чисто) — это частая, важная потребность, API Resources — это часто используемый, ценный инструмент, который отличает хорошо построенные, безопасные API от тех, которые утекают данные или тесно связывают свой выход с базой данных.