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.