O que são API Resources?

Question

Accepted Answer

**API Resources** são classes de transformação que controlam como modelos Eloquent (e coleções) são **serializados para JSON** em respostas de API. Elas permitem que você molde a saída da API com precisão — escolhendo quais campos expor, renomeando-os, formatando valores e incluindo dados relacionados — desacoplando a representação da API da estrutura do banco de dados.

## O problema: expor modelos brutos

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

## A solução: uma 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
```

O método `toArray()` da resource define exatamente a forma do JSON — você controla quais campos aparecem, renomeia e formata-os e inclui resources relacionadas. Campos sensíveis simplesmente não são incluídos.

## Dados condicionais e aninhados

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

## Por que isso importa

API Resources são importantes para construir APIs bem projetadas e seguras no Laravel — elas oferecem controle preciso sobre a saída JSON, o que importa tanto para **segurança** quanto para design de API.

O benefício mais crítico é **prevenir vazamento de dados**: retornar modelos Eloquent diretamente expõe todas as suas colunas (potencialmente incluindo hashes de senha, flags internas ou outros dados sensíveis — uma vulnerabilidade séria), enquanto API Resources permitem que você escolha explicitamente quais campos expor, garantindo que dados sensíveis nunca cheguem aos clientes.

Além de segurança, elas permitem design limpo de API ao **desacoplar a representação da API do schema do banco de dados** — você pode renomear campos, formatar valores (datas, booleanos), estruturar dados aninhados/relacionados e incluir condicionalmente campos baseado em permissões, tudo em uma classe de transformação dedicada.

Isso mantém o contrato da API estável e intencional em vez de acoplado à estrutura interna da tabela.

Compreender API Resources — como elas moldam a saída JSON, o benefício de segurança do controle explícito de campos e recursos como campos condicionais e resources aninhadas — é conhecimento importante para construir APIs Laravel profissionais, já que expor modelos brutos é inseguro e um design pobre.

Como APIs REST/JSON são um uso primário do Laravel hoje, e controlar a forma da resposta (segura e limpa) é uma necessidade comum e importante, API Resources são uma ferramenta valiosa e frequentemente usada que distingue APIs bem construídas e seguras de APIs que vazam dados ou acoplam fortemente sua saída ao banco de dados.