Tema 6 · Paginación & Metadatos

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:

ProductoControllerPaginado.php
Solo lectura
<?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
1 Pregunta
Pregunta 1
¿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.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.