¿Qué son los API Resources?

Question

Accepted Answer

**API Resources** son clases de transformación que controlan cómo los modelos de Eloquent (y colecciones) se **serializan a JSON** para respuestas de API. Te permiten moldear la salida de la API con precisión — eligiendo qué campos exponer, renombrándolos, formateando valores e incluyendo datos relacionados — desacoplando la representación de la API de la estructura de la base de datos.

## Por qué es importante

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

## La solución: un 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
```

El método `toArray()` del recurso define exactamente la forma del JSON — controlas qué campos aparecen, los renombras y formateas, e incluyes recursos relacionados. Los campos sensibles simplemente no se incluyen.

## Datos condicionales y anidados

```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 qué es importante

Los API Resources son importantes para construir APIs bien diseñadas y seguras en Laravel — te dan control preciso sobre la salida JSON, lo que importa tanto para la **seguridad** como para el diseño de APIs.

El beneficio más crítico es **prevenir fugas de datos**: devolver modelos de Eloquent directamente expone todas sus columnas (potencialmente incluyendo hashes de contraseñas, flags internos u otros datos sensibles — una vulnerabilidad grave), mientras que los API Resources te permiten elegir explícitamente qué campos exponer, asegurando que los datos sensibles nunca lleguen a los clientes.

Más allá de la seguridad, habilitan un diseño limpio de API al **desacoplar la representación de la API del esquema de la base de datos** — puedes renombrar campos, formatear valores (fechas, booleanos), estructurar datos anidados/relacionados, e incluir campos condicionalmente basado en permisos, todo en una clase de transformación dedicada.

Esto mantiene el contrato de la API estable e intencional en lugar de acoplado a la estructura interna de la tabla.

Comprender los API Resources — cómo moldean la salida JSON, el beneficio de seguridad del control explícito de campos, y características como campos condicionales y recursos anidados — es un conocimiento importante para construir APIs profesionales en Laravel, ya que exponer modelos raw es inseguro y mal diseño.

Como las APIs REST/JSON son un uso primario de Laravel hoy en día, y como controlar la forma de la respuesta (de forma segura y limpia) es una necesidad común e importante, los API Resources son una herramienta valiosa y frecuentemente utilizada que distingue las APIs bien construidas y seguras de aquellas que filtran datos o acoplan fuertemente su salida a la base de datos.