Tema 2 · Enrutamiento & Versionado

2. Enrutamiento API: Versionado (/api/v1), Grupos y Route::apiResource

Estructura URLs profesionales sin endpoints innecesarios (create/edit) utilizando Route::apiResource y organiza versiones v1/v2 con prefijos limpios.

¿Por qué Route::apiResource en lugar de Route::resource?

En el desarrollo web con vistas HTML, Route::resource('productos', ...) genera 7 rutas, incluyendo /productos/create y /productos/{id}/edit, las cuales sirven para renderizar páginas con formularios HTML.

En una API RESTful esos formularios no existen en el servidor (el formulario lo renderiza React o Flutter). Por ello, Laravel incluye Route::apiResource, que genera exclusivamente los 5 endpoints necesarios para las operaciones de datos:

  • GET /api/productos ➔ index (Listar colección).
  • POST /api/productos ➔ store (Crear recurso).
  • GET /api/productos/{producto} ➔ show (Ver detalle).
  • PUT/PATCH /api/productos/{producto} ➔ update (Modificar).
  • DELETE /api/productos/{producto} ➔ destroy (Eliminar).

Estrategia de Versionado de APIs (v1, v2)

En producción, una API nunca debe cambiar su contrato sin previo aviso porque rompería las aplicaciones móviles ya instaladas en los teléfonos de los usuarios. La buena práctica universal es versionar los endpoints utilizando prefijos de URL:

Route::prefix('v1')->group(function () {
    Route::apiResource('productos', ProductoController::class);
    Route::apiResource('clientes', ClienteController::class);
});

⚡ Definición de Rutas Versionadas y Recursos Anidados en routes/api.php

Estructura profesional de rutas de API con versionado y endpoints públicos y protegidos:

routes/api.php
Solo lectura
<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Api\V1\AuthController;
use App\Http\Controllers\Api\V1\ProductoController;
use App\Http\Controllers\Api\V1\PedidoController;

// Prefijo global de versión 1: /api/v1/...
Route::prefix('v1')->group(function () {

    // Rutas públicas de autenticación y consulta básica
    Route::post('/registro', [AuthController::class, 'registro']);
    Route::post('/login', [AuthController::class, 'login']);
    Route::get('/catalogo', [ProductoController::class, 'catalogoPublico']);

    // Rutas protegidas que exigen token válido de Sanctum
    Route::middleware('auth:sanctum')->group(function () {
        Route::post('/logout', [AuthController::class, 'logout']);
        Route::get('/perfil', [AuthController::class, 'perfil']);

        // CRUD completo de productos mediante apiResource (5 endpoints)
        Route::apiResource('productos', ProductoController::class);

        // Recurso anidado: pedidos de un cliente específico
        Route::apiResource('pedidos', PedidoController::class);
    });
});
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Qué dos acciones/rutas son omitidas por "Route::apiResource()" frente al "Route::resource()" tradicional?
🦉
¿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.