6. Metadatos Globales, Desactivación de Wrap y Paginación Automática
Controla la clave raíz "data", añade metadatos personalizados (versión, enlaces HATEOAS) y aprovecha la paginación nativa de Laravel serializada a JSON.
La Clave Envoltorio (Data Wrapping)
Por defecto, Laravel envuelve las respuestas de los Resources dentro de una clave raíz {"data": { ... }}. Esto permite que el nivel superior del JSON quede reservado para metadatos globales (enlaces de paginación, total de registros, versión de la API).
Si tu equipo o especificación de frontend prefiere no tener la envoltura data en recursos individuales, puedes desactivarla globalmente en el método boot() de AppServiceProvider:
JsonResource::withoutWrapping();
Paginación Automática con Resources
Cuando combinas el método paginate() de Eloquent con Resource::collection(), Laravel genera automáticamente una estructura JSON estándar con dos bloques esenciales:
links:URLs a la primera, última, anterior y siguiente página.meta:Página actual (current_page), total de filas (total), cantidad por página (per_page) y última página (last_page).
⚡ Inyección de Metadatos Adicionales con with() y additional()
Cómo agregar información complementaria (versión, estado, timestamp) a una respuesta de Resource:
<?php
namespace App\Http\Controllers\Api\V1;
use App\Http\Controllers\Controller;
use App\Models\Producto;
use App\Http\Resources\ProductoResource;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
class ProductoController extends Controller
{
/**
* GET /api/v1/productos?page=2
*/
public function index(): AnonymousResourceCollection
{
$productos = Producto::latest()->paginate(15);
// Retornar la colección agregando metadatos personalizados en el nivel superior
return ProductoResource::collection($productos)->additional([
'meta_extra' => [
'api_version' => '1.0.0',
'servidor' => config('app.url'),
'generado_en' => now()->toIso8601String(),
],
'estado' => 'exito'
]);
}
}
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección¿Dónde se debe llamar a "JsonResource::withoutWrapping()" si deseas desactivar la envoltura {"data": ...} en toda la aplicación?
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.🚀 ¿Quieres dominar APIs RESTful con Laravel, Resources & Sanctum y crear proyectos reales?
Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.