Recursos y colecciones en Laravel API

Curso de Estándares y Buenas Prácticas para API REST con Laravel

Contenido del curso

Buenas prácticas a nivel general

Creación del proyecto

Planificación y mantenimiento

Funciones de seguridad

API Testing

API Breaking Changes

Conclusiones

Tomar examen

Cursos Empresas Blog Live Conf Eventos Precios

0:0012:59

Recursos y colecciones en Laravel API

Curso de Estándares y Buenas Prácticas para API REST con Laravel

Clase 9 de 29

Clase 9 / 29

Recursos

Diseñar una API estable empieza por separar la consulta de base de datos de la forma en que se entrega la respuesta. En Laravel, los resources y las collections permiten aislar esa estructura para que cada endpoint devuelva los mismos campos sin importar cómo se construya la consulta. Si trabajas con APIs REST y quieres consistencia editorial en tus respuestas JSON, esta es la pieza que te falta.

¿Qué es un recurso y por qué importa aislarlo?

Un recurso representa el dato que quieres devolver desde tu base de datos, pero con una estructura definida por ti, no por la consulta.

El problema aparece cuando modificas la respuesta endpoint por endpoint. Si en una receta usas select('id','title') y en otra traes el modelo completo, terminas con respuestas inconsistentes: en una aparece el usuario y la categoría, en otra solo el título. El recurso debe ser el mismo sin importar la consulta [01:30].

¿Qué es un API Resource en Laravel? Es una clase que define cómo se transforma un modelo en JSON. Decides qué campos mostrar, cómo nombrarlos y qué relaciones incluir, sin tocar la consulta original.

¿Cómo se crea un recurso con Artisan?

Usas el comando php artisan make:resource CategoryResource. La convención es nombrar la clase con el sufijo Resource para distinguirla.

Esto genera una nueva carpeta y un archivo donde defines el método toArray. Allí estructuras la respuesta de forma personalizada [03:10]:

id: el identificador del modelo.
type: una etiqueta manual como categoría que describe el recurso.
attributes: un arreglo con los campos visibles, por ejemplo name.
relationships: las relaciones asociadas, como las recetas vinculadas.

php public function toArray($request) { return [ 'id' => $this->id, 'type' => 'categoría', 'attributes' => [ 'name' => $this->name, ], 'relationships' => [ 'recetas' => $this->recetas, ], ]; }

¿Cómo uso el recurso desde el controlador?

En el controlador importas la clase con use y la instancias pasando el modelo como parámetro. Para mayor orden, guarda la consulta en una variable y luego retorna el recurso [05:20].

php $category = Category::findOrFail($id); return new CategoryResource($category);

Al visitar el endpoint, la respuesta llega ordenada bajo la llave data, con su id, type, attributes y relationships. Esto es coherencia: cualquier consulta que retorne una categoría va a devolver exactamente esta forma.

¿Y cuándo usar una colección en lugar de un recurso?

Una colección sirve cuando devuelves múltiples elementos. Laravel ofrece el acceso estático ::collection() directamente sobre el recurso [06:40].

php return CategoryResource::collection(Category::all());

Con esto, cada elemento del listado hereda la misma estructura del recurso. El estándar se mantiene: data, id, type, attributes y relationships para cada categoría.

¿Cómo personalizo una colección para que omita relaciones?

A veces el listado no necesita cargar todas las relaciones del recurso individual. La solución es crear una resource collection dedicada con php artisan make:resource CategoryCollection [08:15].

Este archivo es hermano del recurso, pero hereda de ResourceCollection en lugar de JsonResource. Aquí defines un comportamiento distinto usando el método map para iterar la colección y aplicar una transformación a cada elemento.

php public function toArray($request) { return $this->collection->map(function ($category) { return [ 'id' => $category->id, 'type' => 'categoría', 'attributes' => [ 'name' => $category->name, ], ]; })->toArray(); }

¿Por qué se usa toArray() al final del map? Porque Laravel espera un arreglo en la respuesta del recurso. El método map devuelve una colección, así que toArray() la convierte al formato correcto y evita el error de tipos.

¿Cuál es la diferencia práctica entre ambos archivos?

El recurso individual mantiene relaciones completas como las recetas asociadas. La colección, en cambio, entrega un listado más liviano sin esas relaciones, ideal para vistas de índice [10:30].

En el controlador, el método index usa la colección y el método show usa el recurso individual:

php public function index() { return new CategoryCollection(Category::all()); }

public function show($id) { return new CategoryResource(Category::findOrFail($id)); }

Así decides exactamente qué campos mostrar y cuáles ocultar según el contexto, sin tocar nunca la consulta a base de datos. La estructura vive en el recurso, no en el controlador.

Si trabajas con otro framework como Express, Django o Rails, cuéntame en los comentarios cómo logras este mismo aislamiento de la respuesta.

Leonel Veliz

Hace 3 años

En el min 11:35 el data que responde (un solo elemento) viene como un objeto, mientras que si trae mas de un objeto, la API te lo trae como un array.

YO, haría que sin importar el numero de elementos que retorne, retornar siempre un array.

Ya que a la larga es mas simple de manejar el formato de la información.

Podemos discutir si es una buena o una mala idea, pero el punto es el siguiente, es poco probable que las API que estemos construyendo estén en el punto mas optimo como en estos ejemplos, o son APIS heredadas y que le hacemos ciertos refactor.

Entonces, cuando tienes una ruta /categories y /categories/{1} considera que potencialmente al hacer 1 solo formato para ambos endpoint, te ahorras el desarrollo y mantenimiento de 1 formato a lo largo del tiempo

Pedro Keiler Batista Rojo

Hace 3 años

Si pero luego, el front que esta consumiendo, o el cliente que este consumiendo, se le hace confuso el tener que manejar un solo objeto como un array, por experiencia, es mas saludable menejar un elemento como objeto y una coleccion como array.

Saludos

Santiago Velásquez Serna

Hace 3 años

Normalmente cuando requerimos un solo recurso desde el frontend, lo empezamos a utilizar llamando directamente a sus atributos. Es decir si nos traemos una categoria, podemos acceder inmediatamente a su nombre via Category->name, sin embargo, si lo que obtienes es un array, debes hacer un unpacking para acceder a la misma información. Ademas como dijo uno de los compañeros, ya es un estandar el trabajar de esta forma. El cambiar el formato podria permitir malentendidos con las personas del frontend o cualquier sucesor de tu codigo.

Buenas prácticas a nivel general

Buenas prácticas para diseñar una API REST

¿Qué son los HTTP Status Codes?

Qué hace cada método HTTP

Creación del proyecto

Migrações e relações de dados em Laravel

Factories y seeders para poblar tu API en Laravel

Consultas API con Laravel: Rutas y Controladores

Consultas con relaciones en Laravel API

Planificación y mantenimiento

Planificación de rutas REST en Laravel

Recursos y colecciones en Laravel API

Recursos anidados en Laravel API

Cómo reducir 932 consultas con Telescope

CRUD de Recetas con Laravel y Symfony en Visual Studio Code

Validación de Datos en Aplicaciones Web con Laravel

Funciones de seguridad

Autenticación vs. autorización

Proteger rutas de API con Sanctum

Ruta de login y tokens con Sanctum

Corrección de bugs de seguridad en aplicaciones web

Políticas de acceso en Laravel con Artisan

Upload e validação de imagens em Laravel

Qué es autenticación en la web

API Testing

Automatiza pruebas de API en Laravel

Testing de Módulos Administrativos en Visual Studio Code

Testing de recetas con PHP Artisan

Pruebas de Creación de Datos en Aplicaciones Web

Test de actualización de recetas en Laravel

API Breaking Changes

Versionado de API en Laravel con v1 y v2

Desarrollo de API con TDD: Implementación de Versión 2

Conclusiones

Desarrollo de API RESTful con Laravel: Buenas Prácticas y Seguridad

Buenas prácticas finales para tu API en Laravel

Recursos y colecciones en Laravel API