Darkredgm

Una API REST bien diseñada es la columna vertebral de cualquier aplicación moderna. Ya sea que estés construyendo un frontend con Next.js que consume datos de tu backend, una aplicación móvil que necesita sincronizarse con el servidor, o un sistema que se integra con servicios de terceros, la calidad de tu API determinará la velocidad de desarrollo, la seguridad del sistema y la experiencia del usuario final.

En esta guía exhaustiva, compartimos las prácticas que aplicamos en cada proyecto de Darkredgm para construir APIs REST que son un placer de consumir y un bastión de seguridad.

Los Principios REST que Realmente Importan

REST (Representational State Transfer) define un conjunto de restricciones arquitectónicas. En la práctica, los principios que más impactan en la calidad de tu API son:

Recursos como sustantivos — Las URLs representan entidades (/api/users, /api/orders), no acciones. Nunca uses verbos en las URLs como /api/getUsers.
Verbos HTTP como acciones — GET para leer, POST para crear, PUT/PATCH para actualizar, DELETE para eliminar.
Respuestas consistentes — Toda respuesta debe seguir la misma estructura, ya sea exitosa o un error.
Sin estado — Cada petición debe contener toda la información necesaria. El servidor no almacena el estado de la sesión entre peticiones.

Estructura de un Proyecto API en Laravel

Organización de rutas

En Laravel, las rutas de la API se definen en routes/api.php. La clave es organizar las rutas de forma jerárquica y versionada:

// routes/api.php
Route::prefix('v1')->group(function () {
    // Rutas públicas
    Route::post('/auth/login', [AuthController::class, 'login']);
    Route::post('/auth/register', [AuthController::class, 'register']);

    // Rutas protegidas
    Route::middleware('auth:sanctum')->group(function () {
        Route::apiResource('users', UserController::class);
        Route::apiResource('orders', OrderController::class);
        Route::apiResource('products', ProductController::class);
    });
});

El prefijo v1 es fundamental. Cuando necesites hacer cambios que rompan la retrocompatibilidad, puedes crear un v2 sin afectar a los clientes existentes. Esta práctica de versionado de APIs es esencial para cualquier sistema en producción.

Controllers con responsabilidad única

Cada controlador de API debe ser delgado. Su única responsabilidad es recibir la request, validarla, delegarla a un servicio y devolver la response. La lógica de negocio nunca debe vivir en el controlador:

class OrderController extends Controller
{
    public function store(StoreOrderRequest $request)
    {
        $order = $this->orderService->create(
            $request->validated()
        );

        return new OrderResource($order);
    }
}

Autenticación: Laravel Sanctum vs Passport

Cuándo usar Sanctum

Laravel Sanctum es ideal para la mayoría de proyectos. Ofrece autenticación basada en tokens ligeros, perfecta para:

SPAs (Single Page Applications) — Autenticación basada en cookies con protección CSRF.
Aplicaciones móviles — Tokens de API simples que el usuario puede revocar.
APIs internas — Donde controlas tanto el cliente como el servidor.

Cuándo usar Passport

Laravel Passport implementa OAuth2 completo. Úsalo cuando necesites:

Autenticación de terceros — Permitir que aplicaciones externas accedan a tu API en nombre de tus usuarios (como "Iniciar sesión con Google").
Scopes granulares — Diferentes niveles de acceso para diferentes aplicaciones.
Client Credentials — Comunicación servidor-a-servidor sin intervención del usuario.

Regla de oro: si no necesitas OAuth2, no uses Passport. Sanctum cubre el 90% de los casos de uso con una fracción de la complejidad.

Manejo de Errores Consistente

Uno de los mayores indicadores de calidad de una API es cómo maneja los errores. Cada respuesta de error debe incluir:

Código HTTP apropiado — 400 para errores de validación, 401 para no autenticado, 403 para no autorizado, 404 para no encontrado, 422 para entidad no procesable, 500 para errores internos.
Mensaje legible — Una descripción clara de lo que salió mal.
Código de error interno — Un identificador que el frontend puede usar para mostrar mensajes localizados.

// Respuesta de error estandarizada
{
    "success": false,
    "error": {
        "code": "ORDER_INSUFFICIENT_STOCK",
        "message": "No hay suficiente stock para el producto solicitado.",
        "details": {
            "product_id": 42,
            "requested": 10,
            "available": 3
        }
    }
}

En Laravel, implementamos esto con un Exception Handler centralizado que captura todas las excepciones y las transforma en respuestas JSON consistentes.

Rate Limiting y Protección contra Abuso

Toda API pública necesita rate limiting para prevenir abusos. Laravel incluye un middleware de throttle configurable:

// En RouteServiceProvider o directamente en rutas
Route::middleware('throttle:60,1')->group(function () {
    // 60 peticiones por minuto por IP
});

// Rate limiting diferenciado por usuario
RateLimiter::for('api', function (Request $request) {
    return $request->user()
        ? Limit::perMinute(120)->by($request->user()->id)
        : Limit::perMinute(30)->by($request->ip());
});

Los usuarios autenticados obtienen más peticiones por minuto que los anónimos. Los endpoints críticos (como login) deben tener límites más estrictos para prevenir ataques de fuerza bruta.

Paginación, Filtrado y Ordenación

Paginación con cursor vs offset

La paginación tradicional por offset (?page=5&per_page=20) funciona bien para conjuntos de datos pequeños. Pero con millones de registros, el offset se vuelve lento porque la base de datos debe contar todos los registros anteriores.

La paginación por cursor (?cursor=eyJpZCI6MTAwfQ) usa un identificador opaco que apunta directamente al último registro devuelto. Es más eficiente y consistente cuando los datos cambian entre peticiones.

Filtrado flexible con query parameters

Un buen sistema de filtrado permite al cliente solicitar exactamente los datos que necesita:

GET /api/v1/products?category=electronics&price_min=100&price_max=500&sort=-created_at&include=reviews,category

El parámetro include permite al cliente solicitar relaciones específicas, evitando el problema N+1 sin cargar datos innecesarios.

Documentación: Tu API Solo Existe si Está Documentada

Una API sin documentación es una API inutilizable. Las opciones más profesionales para documentar tu API en Laravel son:

Scribe — Genera documentación automáticamente a partir de tus rutas, FormRequests y docblocks. Produce HTML estático y colecciones de Postman.
OpenAPI/Swagger — Estándar de la industria. Puedes usar l5-swagger para generar specs OpenAPI desde anotaciones.
Postman Collections — Exportar colecciones permite que los consumidores de tu API prueben endpoints inmediatamente.

En Darkredgm, documentamos cada endpoint antes de implementarlo. La documentación es el contrato entre frontend y backend, y nos permite trabajar en paralelo desde el día uno.

Testing de APIs: No Negociable

Cada endpoint de tu API debe tener tests automatizados. Laravel facilita esto enormemente con su framework de testing integrado:

public function test_user_can_create_order()
{
    $user = User::factory()->create();
    $product = Product::factory()->create(['stock' => 10]);

    $response = $this->actingAs($user)
        ->postJson('/api/v1/orders', [
            'product_id' => $product->id,
            'quantity' => 2,
        ]);

    $response->assertStatus(201)
        ->assertJsonStructure([
            'data' => ['id', 'total', 'status']
        ]);

    $this->assertDatabaseHas('orders', [
        'user_id' => $user->id,
        'status' => 'pending',
    ]);
}

Los tests no solo verifican que tu API funciona — documentan el comportamiento esperado y protegen contra regresiones cuando refactorizas.

Conclusión: Una API es un Producto

Diseñar una API REST no es una tarea secundaria — es un producto en sí mismo. Los consumidores de tu API (ya sea tu propio frontend, una app móvil o un socio de integración) merecen una experiencia de desarrollo excelente. Eso significa endpoints predecibles, errores claros, documentación completa y rendimiento sólido.

En Darkredgm, tratamos cada API como un producto de primera clase. Si necesitas construir una API que escale con tu negocio y sea un placer de integrar, hablemos.

Guía Completa: Cómo Diseñar APIs REST Profesionales con Laravel