Versionado de API en Laravel con v1 y v2

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:009:39

Versionado de API en Laravel con v1 y v2

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

Clase 26 de 29

Clase 26 / 29

Recursos

El versionado de API te permite evolucionar tu backend sin romper integraciones activas. En Laravel, esta práctica consiste en agrupar rutas, controladores y pruebas bajo prefijos como v1 o v2, de modo que los usuarios antiguos sigan consumiendo la versión que conocen mientras tú desarrollas cambios profundos en paralelo.

¿Qué es el versionado de una API y por qué lo necesitas?

Cuando tu aplicación ya tiene clientes consumiendo endpoints, cualquier cambio fuerte puede romper su integración. La solución es no tocar el código anterior, sino crear una nueva versión.

¿Qué es el versionado de API? Es la técnica de asignar una versión específica (v1, v2) a un conjunto de rutas y funcionalidades, de modo que los cambios futuros no afecten a los usuarios que ya consumen la versión previa.

La idea principal es separar por carpetas y prefijos. La v1 queda congelada para los clientes existentes, y la v2 recibe los cambios radicales. Así ganas flexibilidad y desarrollo controlado [01:30].

¿Cómo separar las rutas en archivos api_v1.php y api_v2.php?

El primer paso es dividir las rutas en archivos independientes. Crea api_v1.php y api_v2.php dentro de la carpeta de rutas, y desde el archivo principal impórtalos usando la constante de directorio actual.

php require DIR . '/api_v1.php'; require DIR . '/api_v2.php';

Dentro de cada archivo, define el prefijo correspondiente para que el sistema responda a URLs como api/v1/categorias. En la versión uno usas v1, y más adelante en la versión dos configuras v2.

php Route::prefix('v1')->group(function () { Route::apiResource('categorias', CategoriaController::class); });

Este prefijo es lo que separa visualmente y técnicamente las dos versiones a nivel de rutas [02:45].

¿Cómo organizar los controladores por versión en Laravel?

No basta con separar las rutas. Los controladores también deben vivir en carpetas distintas para evitar conflictos cuando una funcionalidad cambie radicalmente entre versiones.

Crear la carpeta v1 dentro de Controllers/Api

Dentro de app/Http/Controllers/Api, crea una carpeta llamada v1 y mueve allí los controladores existentes: categorías, recetas y etiquetas. Cada uno representa un recurso de tu API.

Actualizar el namespace de cada controlador

Al mover los archivos cambia su ubicación, así que debes actualizar el namespace de cada controlador para que apunte a App\Http\Controllers\Api\V1.

php namespace App\Http\Controllers\Api\V1;

Luego, en api_v1.php, importa los controladores desde ese mismo namespace. Si saltas este paso, Laravel no encuentra las clases y el sistema colapsa [04:10].

¿Cómo adaptar los tests al sistema de versiones?

Al reorganizar controladores, los tests existentes fallan porque las rutas ya no existen en la raíz, sino bajo v1. La solución es replicar la misma estructura de carpetas dentro del directorio de pruebas.

Crea la carpeta Http dentro de tests/Feature.
Dentro de Http crea Controllers.
Dentro de Controllers crea Api.
Dentro de Api crea V1.

Mueve allí los tests de categorías, recetas y etiquetas. Cada test ahora valida específicamente el comportamiento de la versión uno.

¿Por qué versionar también los tests? Porque cada versión de la API tiene su propia lógica de negocio. Si mezclas tests, no sabrás si un fallo viene de v1 o v2.

Después actualiza el namespace de cada test para que coincida con la nueva ruta: Tests\Feature\Http\Controllers\Api\V1. También ajusta las URLs dentro de cada prueba para que apunten a api/v1/categorias, api/v1/recetas y api/v1/etiquetas [05:50].

¿Cómo verificar que el versionado funciona correctamente?

Una vez actualizadas rutas, controladores y tests, ejecuta la suite completa desde la terminal.

bash php artisan test

Si todo está bien configurado, verás cómo pasan los tests de index, show, update y destroy para la versión uno de cada recurso. Ese resultado verde confirma que tu API responde bajo el prefijo v1 sin romper la lógica original.

Complementa la verificación probando los endpoints desde Postman. Llama a GET api/v1/categorias y revisa el JSON de respuesta. Cuando estés listo para introducir cambios fuertes, repite todo el proceso bajo el prefijo v2 y deja v1 intacta.

Esta es la base de una buena práctica profesional: agregar funcionalidad nueva sin afectar a los usuarios antiguos. ¿En qué momento de tu proyecto crees que sería el ideal para crear la v2? Comparte tu caso en los comentarios.

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

Versionado de API en Laravel con v1 y v2