Tema 8 · Endpoint GET

8. Endpoints GET: Lectura de Colecciones, Paginación y Filtros por Parámetro

Implementa consultas de listado completo y detalle individual por ID (/api/productos y /api/productos/10) con soporte para paginación (limit/offset).

Diseño de Endpoints de Lectura (GET)

En una API RESTful bien estructurada, las consultas de lectura siguen dos patrones canónicos:

  • GET /api/productos: Retorna la colección de recursos (con filtros y paginación).
  • GET /api/productos/{id}: Retorna el detalle individual de un único recurso. Si no existe, devuelve 404 Not Found.

Paginación Segura con LIMIT y OFFSET

Nunca permitas que un endpoint devuelva todos los registros de una tabla sin límite (SELECT * FROM productos). Si la tabla crece a 100.000 filas, la memoria del servidor colapsará y el cliente se bloqueará.

La paginación estándar se controla mediante parámetros de consulta (Query Parameters):

  • pagina (o page): Página actual (por defecto 1).
  • limite (o limit): Cantidad de elementos por página (por defecto 15, con un máximo de 100).
  • Fórmula del desplazamiento: $offset = ($pagina - 1) * $limite;

⚡ Controlador de Lectura con Colección Paginada y Detalle Individual

Implementación en PHP puro para manejar GET /productos y GET /productos/{id}:

ProductoControladorGET.php
Solo lectura
<?php
declare(strict_types=1);

final class ProductoControlador
{
    /**
     * GET /api/productos?pagina=1&limite=10
     */
    public function listar(): void
    {
        $db = Database::getConnection();

        // 1. Sanitizar parámetros de paginación
        $pagina = max(1, (int)($_GET['pagina'] ?? 1));
        $limite = min(100, max(1, (int)($_GET['limite'] ?? 10)));
        $offset = ($pagina - 1) * $limite;

        // 2. Obtener el conteo total de registros
        $total = (int)$db->query('SELECT COUNT(*) FROM productos')->fetchColumn();

        // 3. Obtener los registros paginados con consulta preparada
        $stmt = $db->prepare('SELECT id, nombre, precio, stock, creado_en FROM productos ORDER BY id DESC LIMIT :limit OFFSET :offset');
        $stmt->bindValue(':limit', $limite, PDO::PARAM_INT);
        $stmt->bindValue(':offset', $offset, PDO::PARAM_INT);
        $stmt->execute();
        $productos = $stmt->fetchAll();

        // 4. Emitir respuesta con metadatos de paginación
        ApiResponse::success([
            'items' => $productos,
            'paginacion' => [
                'total'        => $total,
                'pagina_actual'=> $pagina,
                'por_pagina'   => $limite,
                'total_paginas'=> (int)ceil($total / $limite),
            ]
        ], 'Colección de productos obtenida');
    }

    /**
     * GET /api/productos/{id}
     */
    public function ver(int $id): void
    {
        $db = Database::getConnection();
        $stmt = $db->prepare('SELECT * FROM productos WHERE id = :id');
        $stmt->execute(['id' => $id]);
        $producto = $stmt->fetch();

        if (!$producto) {
            ApiResponse::error("Producto con ID $id no encontrado", 404);
        }

        ApiResponse::success($producto, 'Detalle de producto obtenido');
    }
}
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Por qué se debe vincular el parámetro :limit en PDO usando bindValue con PDO::PARAM_INT en lugar de inyectarlo directo en el execute([":limit" => $limite])?
🦉
¿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 PHP Puro, JSON & JWT 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.