Crear una API REST con Laravel: rutas, JSON, autenticación y seguridad

REST no es simplemente poner /api/ delante de una URL

Una API REST suele organizar su interfaz alrededor de recursos.

Por ejemplo:

/productos
/usuarios
/pedidos
/categorias

Los métodos HTTP expresan qué operación quieres realizar sobre esos recursos.

Define el contrato inicial de la API mediante rutas

Podemos comenzar con dos endpoints públicos.

<?php

use App\Http\Controllers\ProductoController;
use Illuminate\Support\Facades\Route;

Route::get(
    '/productos',
    [ProductoController::class, 'index']
);

Route::get(
    '/productos/{producto}',
    [ProductoController::class, 'show']
);

El primer endpoint representa la colección.

El segundo representa un producto específico.

Después puedes añadir escritura

Route::post(
    '/productos',
    [ProductoController::class, 'store']
);

Route::patch(
    '/productos/{producto}',
    [ProductoController::class, 'update']
);

Route::delete(
    '/productos/{producto}',
    [ProductoController::class, 'destroy']
);

Laravel también puede declarar este patrón mediante una ruta de recurso.

Route::apiResource(
    'productos',
    ProductoController::class
);

El objetivo no es utilizar menos líneas a cualquier precio.

Lo importante es que la estructura de endpoints sea coherente y predecible.

Revisa las rutas que realmente registró Laravel

Cuando una URL no responde como esperas, verificar las rutas registradas puede ahorrarte mucho tiempo.

php artisan route:list

Esto permite comprobar:

Devuelve una colección paginada de productos

<?php

public function index()
{
    $productos = Producto::query()
        ->where('activo', true)
        ->orderBy('id')
        ->paginate(20);

    return ProductoResource::collection(
        $productos
    );
}

Ya tenemos varias decisiones importantes:

solamente productos activos, orden definido y paginación.

Evita comenzar con Producto::all()

Una API que funciona con veinte registros puede convertirse en un problema cuando la tabla alcanza cientos de miles.

Laravel puede resolver automáticamente el model asociado a un parámetro de ruta

Nuestra ruta contiene:

/productos/{producto}

El controller puede recibir directamente una instancia del model.

<?php

public function show(
    Producto $producto
) {
    return new ProductoResource(
        $producto
    );
}

Esto evita repetir manualmente una búsqueda por ID en cada acción.

Cuando las reglas crecen, sácalas del controller

Puedes crear una clase dedicada a validar la creación del recurso.

php artisan make:request StoreProductoRequest

Allí puedes declarar las reglas.

<?php

public function rules(): array
{
    return [
        'nombre' => [
            'required',
            'string',
            'max:150'
        ],
        'sku' => [
            'required',
            'string',
            'max:100',
            'unique:productos,sku'
        ],
        'precio' => [
            'required',
            'numeric',
            'min:0'
        ]
    ];
}

El controller queda más enfocado.

<?php

public function store(
    StoreProductoRequest $request
) {
    $producto = Producto::create(
        $request->validated()
    );

    return (new ProductoResource($producto))
        ->response()
        ->setStatusCode(201);
}

Utiliza códigos de estado que expliquen qué ocurrió

El código de estado forma parte del contrato de tu API.

Actualiza únicamente los campos permitidos por el contrato

<?php

public function update(
    UpdateProductoRequest $request,
    Producto $producto
) {
    $producto->update(
        $request->validated()
    );

    return new ProductoResource(
        $producto->refresh()
    );
}

Aquí el Form Request define qué acepta la operación.

No deberías permitir que el cliente cambie campos internos simplemente porque existen en la tabla.

Una eliminación correcta puede responder sin contenido

<?php

public function destroy(
    Producto $producto
) {
    $producto->delete();

    return response()->noContent();
}

El hecho de que el endpoint exista no significa que cualquier usuario deba poder ejecutarlo.

Antes de eliminar necesitas resolver autorización y reglas relacionadas con el negocio.

Los parámetros de consulta pueden permitir buscar sin crear un endpoint para cada filtro

Un cliente podría solicitar:

GET /api/productos?activo=1&categoria=5

El controller puede construir la consulta progresivamente.

$query = Producto::query();

if ($request->filled('activo')) {

    $query->where(
        'activo',
        $request->boolean('activo')
    );

}

if ($request->filled('categoria')) {

    $query->where(
        'categoria_id',
        $request->integer('categoria')
    );

}

$productos = $query
    ->orderBy('id')
    ->paginate(20);

Valida también los filtros

El hecho de que estén en una URL no significa que sean confiables.

Los nombres de columnas dinámicas deberían limitarse a valores permitidos

No conviene permitir que cualquier texto recibido determine directamente una columna SQL.

Puedes mantener una lista explícita.

$permitidos = [
    'nombre',
    'precio',
    'created_at'
];

$orden = $request->input(
    'orden',
    'created_at'
);

if (! in_array(
    $orden,
    $permitidos,
    true
)) {
    $orden = 'created_at';
}

$productos = Producto::query()
    ->orderBy($orden)
    ->paginate(20);

El problema N+1 también puede aparecer dentro de tus Resources

Si transformas una colección y durante cada transformación accedes a una relación no cargada, puedes generar muchas consultas.

100 productos
+
1 consulta por categoría
=
muchas consultas adicionales

Por eso, la construcción de la consulta y la transformación JSON deberían diseñarse juntas.

Una API de terceros puede utilizar Bearer tokens, pero una SPA propia tiene necesidades diferentes

Cuando utilizas tokens personales para una API, el cliente puede enviar:

Authorization: Bearer TU_TOKEN

Pero no deberías asumir que una SPA propia necesita guardar manualmente un token de larga duración en JavaScript.

La estrategia de autenticación depende de quién consume la API.

Los tokens pueden limitar capacidades, pero eso tampoco sustituye la autorización del recurso

Puedes imaginar capacidades como:

productos:read
productos:create
productos:update

Un token podría tener permiso para actualizar productos, pero tu aplicación todavía podría necesitar comprobar:

empresa, propietario, rol o estado del recurso.

CORS aparece cuando un frontend del navegador intenta consumir tu API desde otro origen

Por ejemplo:

https://app.ejemplo.com

        ↓

https://api.ejemplo.com

El navegador aplica reglas de origen que debes tener en cuenta.

CORS no es autenticación

Permitir un origen no demuestra la identidad del usuario.

CORS tampoco protege una API de clientes fuera del navegador

Un servidor, script o herramienta HTTP no funciona bajo las mismas restricciones del navegador.

Mantén una estructura de respuesta predecible

Si una colección devuelve:

{
    "data": [
        {
            "id": 1,
            "nombre": "Monitor"
        }
    ]
}

no conviene que otro endpoint equivalente cambie arbitrariamente a:

{
    "resultado": {
        "productos": [...]
    }
}

salvo que exista una razón clara para ese contrato.

La consistencia reduce lógica especial en cada cliente.

Piensa qué ocurrirá si el cliente repite una solicitud

Un usuario puede presionar dos veces un botón.

Una red puede cortar la respuesta después de que el servidor procesó la operación.

El cliente puede intentar nuevamente.

Para una consulta GET suele ser sencillo

Repetir la misma lectura normalmente no crea un nuevo recurso.

Para pagos, pedidos u operaciones sensibles necesitas más cuidado

Puede ser necesario diseñar mecanismos que eviten duplicados durante reintentos.

Una API pública necesita límites además de autenticación

Incluso un usuario válido puede generar un volumen excesivo de solicitudes.

El rate limiting puede ayudar a proteger:

Los límites pueden depender del endpoint, usuario, plan o tipo de operación.

Un límite adecuado para consultar productos puede ser completamente distinto al de generar un informe pesado.

Un controller no debería contener toda la lógica de una API

Al principio es normal que un controller haga cosas sencillas.

Pero imagina este proceso:

Validar request
      ↓
Comprobar stock
      ↓
Calcular precios
      ↓
Aplicar descuentos
      ↓
Crear pedido
      ↓
Crear items
      ↓
Reservar stock
      ↓
Emitir evento

Todo eso dentro de store() puede convertir rápidamente el controller en una clase difícil de probar y modificar.

Puedes separar el caso de uso

<?php

final class CrearPedido
{
    public function ejecutar(
        DatosPedido $datos
    ): Pedido {

        // Reglas del proceso.

        return $pedido;
    }
}

Y dejar al controller principalmente como adaptador HTTP.

Una API lenta muchas veces es una base de datos lenta disfrazada de problema HTTP

Antes de culpar al framework, revisa:

Una ruta muy elegante puede terminar ejecutando cientos de consultas SQL.

Documenta la API pensando en quien tendrá que consumirla

El consumidor necesita saber:

Una API sin documentación obliga al consumidor a descubrir el contrato mediante prueba y error.

OpenAPI puede ayudarte a formalizar ese contrato

Especialmente cuando existen múltiples clientes, equipos o integraciones externas.

Laravel puede exponer datos propios y consumir modelos de inteligencia artificial al mismo tiempo

Por ejemplo, podrías construir:

Frontend
   ↓
Laravel API
   ↓
Autenticación
   ↓
MySQL
   ↓
Contexto autorizado
   ↓
Modelo de IA
   ↓
Respuesta JSON

Laravel puede controlar usuarios, permisos, consumo, historial y datos, mientras una API externa proporciona la capacidad de IA.

En qué orden aprender APIs REST con Laravel

Una buena API Laravel es un contrato HTTP estable, no simplemente un controller que devuelve JSON